---
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.'
---

# 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.
- Creating editable tables with Python-authoritative state, validation, and persistence.
- 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

### Styling And Customization

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

- app-wide and page-level color themes, dark mode, and semantic CSS tokens
- Tailwind and Quasar utility classes
- scoped CSS properties and stable application classes
- responsive page composition and static asset loading
- cosmetic treatment of controls, surfaces, typography, and visual states
- visual validation at supported viewport sizes

### Component Mechanics

Load [component mechanics](./references/component-mechanics.md) for:

- the NiceGUI Python wrapper, element bridge, Quasar component, and Vue runtime boundaries
- deciding between constructors, bindings, Quasar props, events, slots, and frontend methods
- server-client state and event flow
- detached content and external icon assets
- source research against the installed NiceGUI and bundled Quasar versions
- `ui.select` and `ui.icon` mechanics and caveats
- scoped component slots and their interaction contracts

### Editable Tables

Load [editable tables](./references/tables.md) for:

- Python-authoritative editable `ui.table` state
- rendering dataframe records into row-scoped bindable dataclasses
- stable row identity across sorting, filtering, and pagination
- NiceGUI editors in Quasar `body-cell-*` scoped slots
- validation, persistence, rejection, and canonical row refresh
- the full `body` slot required when escalating to `QPopupEdit`

### 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 [styling and customization](./references/styling-and-customization.md) only when page layout or visual customization is in scope.

### Page Or Component Work

1. Load [application architecture](./references/architecture.md) for page and component ownership decisions.
2. Load [styling and customization](./references/styling-and-customization.md) for themes, layout, responsive presentation, utility classes, or CSS.
3. Load [component mechanics](./references/component-mechanics.md) when behavior must be mapped across NiceGUI, Quasar, and Vue, or when detached content and component-specific behavior are involved.
4. Load [editable tables](./references/tables.md) when table cells accept user changes or `QPopupEdit` is being considered.
5. 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.
- Discover component capabilities through NiceGUI docs and constructors, then the wrapped Quasar API.
- Keep editable table records authoritative in Python; send stable row keys with edit proposals and reassert canonical rows after validation.
- Research the current NiceGUI and Quasar source documentation before generating component-specific code or CSS.
- Prefer constructor arguments and native Quasar features through NiceGUI; use Tailwind for structure and scoped static CSS for stable fine tuning.
- 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