NiceGUI Application Guide¶

Use this skill to choose the smallest supporting reference for a NiceGUI task. The pages cover different ownership boundaries; do not load the whole reference set.

Workflow¶

Inspect the target project's pinned NiceGUI version, entry point, and existing page/component patterns.
Match the request to one row in the routing table and load that primary reference.
Load the optional companion only when the task crosses the boundary named in the last column.
Prefer NiceGUI's typed constructor, binding, or helper API; descend to Quasar props, events, slots, or methods only when the wrapper does not expose the required behavior.
Validate the changed behavior with a focused test. For visual work, also check the supported mobile, landscape desktop, and portrait desktop viewports.

Task Routing¶

Task or symptom	Load first	Add only when
Choose package boundaries, dependency direction, thin page composition, reusable component factories, returned dataclass component handles, page registration, health routes, or optional subsystem placement	application architecture	Add binding dataclasses for the component handle's binding graph or FastAPI and Uvicorn startup for concrete ASGI ownership.
Decide between `ui.run()` and `ui.run_with()`, compose a parent FastAPI app, define lifespan ordering, build an app factory, configure typed settings, expose a project script, or handle reload/workers	FastAPI and Uvicorn startup	Add configuration and deployment for concrete `ui.run` options, hosting, native mode, or packaging.
Configure `ui.run`, consume `app.urls`, select NiceGUI environment variables, run behind Docker or a reverse proxy, enable HTTPS, build a native app, package with PyInstaller or Nuitka, or evaluate NiceGUI On Air	configuration and deployment	Add FastAPI and Uvicorn startup when a parent ASGI app, app factory, lifespan, reload, or workers own part of startup.
Choose a `ui.*` constructor, binding, Quasar prop, event, slot, or frontend method; diagnose model events, event payloads, scoped-slot props, detached popups, `ui.select`, or `ui.icon`	component mechanics	Add source documentation when the installed wrapper or bundled Quasar version must be verified.
Build page shells, rows, columns, grids, widths, overflow, responsive reflow, typography, font loading, static assets, or deliberate scaling	page structure, typography, and scaling	Add component mechanics when layout depends on a Quasar prop, slot, popup, or generated component structure.
Configure `app.colors()`, `ui.colors()`, semantic or fixed Quasar colors, custom color names, component color values, CSS color variables, or `ui.dark_mode()`	NiceGUI and Quasar color theming	Add page structure, typography, and scaling only when the task also changes physical layout or CSS loading.
Model typed page or component state with `binding.bindable_dataclass`, return a bound component handle, understand propagation and transform direction, bind nested values, avoid active-link polling, or design projection/persistence rollback	binding dataclasses	Add application architecture for the render-factory and thin-page boundary or component mechanics for browser-originated proposals.
Customize `ui.table` or QTable columns, formatting, classes, props, responsive density, toolbar controls, visible columns, empty states, named slots, or frontend methods	table customization	Add editable tables only when cells also accept server-authoritative edits.
Make `ui.table` cells editable with stable row keys, dataframe projections, row-scoped dataclasses, validation, touched rows, selection-preserving refresh, or `QPopupEdit`	editable tables	Follow its links to binding or component mechanics only when changing the underlying projection or event bridge.
Implement uploads, form submission, SSE versus WebSockets, background jobs, duplicate-submit guards, or `@ui.refreshable` and `@ui.refreshable_method` component regions	interaction patterns	Add application architecture for the reusable component contract or binding dataclasses when state propagation itself is the problem.
Build or explain URL-backed tabs, persistent tab panels, `ui.sub_pages` route adapters, browser-history synchronization, or parameterized routes that share one tab	URL-backed tabs with sub pages	Add binding dataclasses only when the route-backed state grows beyond the single field shown in the example.
Investigate upload errors, async UI races, stale assets, navigation/state drift, or perform a compact production-readiness review	troubleshooting and quality gates	Follow the symptom to one detailed reference above.
Verify a framework claim against primary NiceGUI, FastAPI, Uvicorn, Tailwind, Quasar, SQLAlchemy, Pydantic, or LangGraph documentation	source documentation	Use a task page first when implementation guidance, not source lookup, is needed.

Boundary Rules¶

Use application architecture for module ownership, not for page geometry or low-level component behavior.
Use FastAPI and Uvicorn startup to decide which process owns startup; use configuration and deployment after that decision for runtime, native, hosting, and packaging settings.
Keep page functions thin: compose page shells and returned component handles there; keep each component's element tree, bindings, callbacks, and bounded refreshes in its render factory or component object.
Use page structure, typography, and scaling for physical layout. Use component mechanics for the behavior crossing NiceGUI, Quasar, Vue, and browser boundaries.
Start read-only table presentation and QTable control work in table customization; keep editable state and validation in editable tables.
Use binding dataclasses for the binding graph and Python model projections. Use interaction patterns for user workflows such as upload, submit, refresh, streaming, and background work.
Start editable-table work in editable tables. It already identifies the exact binding and event sections needed by that pattern.
Treat source documentation as a source index, not as an implementation workflow.

Runnable Examples¶

Load an example only when its exact mechanic matches the task:

binding transforms: bindable_dataclass, ui.date, and typed forward/backward conversion.
select events: on_change, generic Quasar events, update:model-value, browser-to-Python payload forwarding, and programmatic value changes.
table customization: raw-value sorting with cosmetic prefix, suffix, and datetime formatting; dynamic classes; QTable props; toolbar and cell slots; filtering; visible columns; and empty states.
editable table: dataframe-to-row state, named QTable cell slots, controlled editors, dialog-based whole-row save/cancel edits, Python validation, touched rows, and canonical row refresh.
tabbed sub-pages: a persistent shell with URL-backed tabs, tab panels, browser-history navigation, and retained state for a parameterized report route. See the reference explanation for the ownership model and behavioral boundaries.

Defaults That Span References¶

Keep composition, transport, services, pages, and components directionally separated.
Prefer reusable render functions that return typed component handles; use bindable dataclass fields for the state intentionally exposed to composition code.
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 to unrelated polling.
Keep browser-originated values as proposals; validate and normalize them in Python before mutating authoritative state.
Prefer NiceGUI context managers and ui.* elements over raw Vue templates. Keep application logic and authoritative state in Python; use minimal browser expressions only for scoped-slot values or client-only behavior, following Python-owned slot composition.
For each presentation requirement, check the component's typed Python arguments and helpers before using .props(...) or .classes(...). Create an application class and add CSS only when no Python API, documented component prop or slot, or existing utility class can express the requirement.
Use NiceGUI context managers for element structure and Tailwind for generic layout, spacing, responsive behavior, and typography. Keep Quasar classes for semantic palette roles or component-specific geometry, and use Quasar props for component behavior and density; see combining Tailwind with Quasar utilities.
Provide loading, success, and failure states for user-triggered work.
Verify component-specific behavior against the installed NiceGUI version and its bundled Quasar version.

Completion Check¶

Before finishing, distinguish target-repository facts from reference recommendations, cite the supporting page used for framework-specific claims, state unresolved assumptions, and report the focused behavior and viewport checks performed.