---
name: nicegui
description: 'Reference hub for NiceGUI and FastAPI application structure, typed configuration, ASGI and Uvicorn startup, UI composition, styling, bindable state, interactions, troubleshooting, testing, and source documentation. Use when planning, implementing, reviewing, deploying, or debugging NiceGUI applications; load only the references relevant to the task.'
x-personal-mcp:
  id: nicegui
  version: 2.4.0
  tags:
    - nicegui
    - fastapi
    - asgi
    - uvicorn
    - pydantic-settings
    - configuration
    - deployment
    - ui
    - architecture
    - scaffolding
    - customization
    - frontend
    - testing
    - source-docs
  capabilities:
    - resource://skills/nicegui/document
---

# NiceGUI Reference

Use this skill as a progressive reference for NiceGUI applications built with FastAPI. Start with the routing map, load only the material needed for the current question, and reconcile it with the target project's NiceGUI version and established conventions.

## When to Use

- Planning or reviewing NiceGUI application structure and FastAPI composition.
- Building or refactoring pages, components, layouts, and static assets.
- Modeling UI state with bindings or bindable dataclasses.
- Implementing forms, uploads, refreshes, live updates, or background work.
- Diagnosing UI state, concurrency, navigation, or asset problems.
- Verifying framework behavior against primary documentation.

## How to Use This Skill

1. Classify the request using the discovery map below.
2. Load the smallest relevant reference, or at most two references for a mixed concern.
3. Inspect the target repository before applying guidance; preserve its sound local patterns.
4. Check the pinned NiceGUI and integration versions before relying on version-specific APIs.
5. Validate the changed behavior with focused tests and, for UI work, relevant viewport checks.

## Progressive Discovery Map

### Application Architecture

Load [application architecture](./references/architecture.md) for:

- FastAPI app factories and lifespan ownership
- package boundaries and dependency direction
- page registration and health routes
- optional persistence, LangGraph, or mounted documentation
- async responsiveness and baseline tests

### FastAPI And Uvicorn Startup

Load [FastAPI and Uvicorn startup](./references/fastapi-uvicorn-startup.md) for:

- choosing between `ui.run()` and `ui.run_with()`
- understanding the parent FastAPI app and NiceGUI's internal app
- composing ASGI lifespan and mounted routes
- loading one typed settings snapshot for server and application configuration
- serving an app instance or factory with Uvicorn
- exposing programmatic startup through `[project.scripts]`
- reload, worker, and process-local state constraints

### Components And Styling

Load [architecture and styling](./references/architecture-and-styling.md) for:

- page, component, and service boundaries
- component extraction decisions
- Quasar props, Tailwind utilities, and custom CSS boundaries
- responsive layout and static asset conventions
- uniformly scaling dialogs on mobile
- preserving Quasar field proportions
- keeping detached `QSelect` menus anchored
- sizing scrollable dialog cards under CSS `zoom`
- validating zoomed controls with Playwright or a browser

### Bindable State

Load [bindable dataclasses](./references/binding-dataclasses.md) for:

- typed local UI state
- propagation and refresh behavior
- nested structures and strict bindings
- mutable defaults, performance, and version notes

### Interaction Patterns

Load [interaction patterns](./references/interaction-patterns.md) for:

- uploads and form submission
- explicit refreshes
- server-sent events and WebSockets
- background work and duplicate-submission guards

### Troubleshooting And Quality

Load [troubleshooting and quality gates](./references/troubleshooting-and-quality-gates.md) for:

- upload failures and UI race conditions
- stale assets and navigation drift
- responsiveness, accessibility, reliability, and maintainability checks

### Primary Sources

Load [source documentation](./references/source-documentation.md) when:

- behavior is version-sensitive or uncertain
- an integration recommendation needs verification
- upstream NiceGUI, FastAPI, Tailwind, Quasar, SQLAlchemy, Pydantic, or LangGraph documentation is required

## Common Discovery Paths

### New Application Or Architecture Review

1. Load [application architecture](./references/architecture.md).
2. Add [FastAPI and Uvicorn startup](./references/fastapi-uvicorn-startup.md) when FastAPI owns the application or startup must be exposed as a project command.
3. Add [architecture and styling](./references/architecture-and-styling.md) only when page and component design is in scope.

### Page Or Component Work

1. Load [architecture and styling](./references/architecture-and-styling.md).
2. Add [interaction patterns](./references/interaction-patterns.md) or [bindable dataclasses](./references/binding-dataclasses.md) according to the page behavior.

### Debugging Or Production Review

1. Start with [troubleshooting and quality gates](./references/troubleshooting-and-quality-gates.md).
2. Follow the symptom to one detailed reference.
3. Confirm uncertain behavior in [source documentation](./references/source-documentation.md).

## General Defaults

- Keep composition, transport, services, pages, and components directionally separated.
- Keep business logic out of UI components and event handlers.
- Avoid blocking I/O and CPU-heavy work in the UI event loop.
- Prefer event-driven updates and explicit refreshes over unrelated polling.
- Prefer Tailwind utilities, then Quasar props, then reusable component helpers; use minimal shared CSS when those are insufficient.
- Provide loading, success, and failure states for user-triggered work.
- Treat version-specific guidance as a prompt to verify the project's dependency version.

## Reference Use Contract

When applying this skill:

- return only guidance relevant to the current task
- distinguish repository facts from reference recommendations
- cite the appropriate source reference for framework-level claims
- state assumptions when application requirements are missing
- report the focused checks used to validate implementation changes