# zauberzeug/nicegui architecture

> Architecture diagram of the GitHub repository zauberzeug/nicegui, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zauberzeug/nicegui
- Repository: https://github.com/zauberzeug/nicegui

## Overview

NiceGUI is a Python framework for building browser-based interfaces, with an optional native-window mode. The principal workflow is that a Python application declares pages and UI elements; the runtime serves a rendered client, then routes browser interactions back to Python event handlers. The README also describes binding and refreshable functions, timers, persistence, custom routes, and a broad set of higher-level visualization and interaction elements, which are shown as distinct capabilities. The source excerpts support key client, element, storage, and native-event responsibilities; wiring for unsampled subsystems is kept conservative.

Main entry points: [`nicegui/elements`](https://github.com/zauberzeug/nicegui/tree/main/nicegui/elements) (UI elements), [`nicegui/ui.py`](https://github.com/zauberzeug/nicegui/blob/main/nicegui/ui.py) (UI API), [`nicegui/app/app.py`](https://github.com/zauberzeug/nicegui/blob/main/nicegui/app/app.py) (App lifecycle), [`nicegui/client.py`](https://github.com/zauberzeug/nicegui/blob/main/nicegui/client.py) (Client rendering)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Python authoring"]
  node_ui_api["UI API<br/>[ui.py]"]
  node_pages["Pages and routes<br/>[page.py]"]
  node_elements["UI elements"]
  node_highlevel["Visualizations and media"]
end

subgraph group_runtime["Application runtime"]
  node_app["App lifecycle<br/>[app.py]"]
  node_server["ASGI server<br/>[server.py]"]
  node_client["Client rendering<br/>[client.py]"]
  node_element_core["Element model<br/>[element.py]"]
  node_events["Event dispatch<br/>[events.py]"]
  node_outbox["Client updates<br/>[outbox.py]"]
end

subgraph group_browser["Browser interface"]
  node_frontend["Vue and Quasar UI<br/>[nicegui.js]"]
  node_query["DOM querying<br/>[query.js]"]
end

subgraph group_state["State and extensions"]
  node_binding["Binding and refresh<br/>[binding.py]"]
  node_timers["Timers<br/>[timer.py]"]
  node_storage["Per-user persistence<br/>[storage.py]"]
  node_persistence[("Persistence backends")]
  node_custom_routes["Custom data routes<br/>[app.py]"]
  node_native["Native window mode"]
  node_native_events["Native event manager<br/>[event_manager.py]"]
end

node_developer(("App developer"))
node_browser(("Browser user"))

node_developer -->|"declares interface"| node_ui_api
node_ui_api -->|"registers pages"| node_pages
node_ui_api -->|"creates elements"| node_elements
node_ui_api -->|"creates components"| node_highlevel
node_ui_api -->|"configures runtime"| node_app
node_pages -->|"builds page"| node_client
node_elements -->|"uses model"| node_element_core
node_highlevel -->|"uses model"| node_element_core
node_app -->|"starts server"| node_server
node_server -->|"serves requests"| node_app
node_client -->|"serializes elements"| node_element_core
node_client -->|"serves interface"| node_browser
node_browser -->|"uses interface"| node_frontend
node_frontend -->|"sends events"| node_client
node_client -->|"dispatches events"| node_events
node_events -->|"invokes handlers"| node_elements
node_elements -->|"queues updates"| node_outbox
node_outbox -->|"sends updates"| node_frontend
node_query -->|"updates DOM"| node_browser
node_binding -->|"refreshes values"| node_elements
node_timers -->|"triggers updates"| node_elements
node_storage -->|"uses backend"| node_persistence
node_app -->|"owns storage"| node_storage
node_custom_routes -->|"serves responses"| node_browser
node_app -.->|"configures window"| node_native
node_native_events -.->|"dispatches handlers"| node_events

click node_ui_api "https://github.com/zauberzeug/nicegui/blob/main/nicegui/ui.py"
click node_pages "https://github.com/zauberzeug/nicegui/blob/main/nicegui/page.py"
click node_elements "https://github.com/zauberzeug/nicegui/tree/main/nicegui/elements"
click node_highlevel "https://github.com/zauberzeug/nicegui/tree/main/nicegui/elements"
click node_app "https://github.com/zauberzeug/nicegui/blob/main/nicegui/app/app.py"
click node_server "https://github.com/zauberzeug/nicegui/blob/main/nicegui/server.py"
click node_client "https://github.com/zauberzeug/nicegui/blob/main/nicegui/client.py"
click node_element_core "https://github.com/zauberzeug/nicegui/blob/main/nicegui/element.py"
click node_events "https://github.com/zauberzeug/nicegui/blob/main/nicegui/events.py"
click node_outbox "https://github.com/zauberzeug/nicegui/blob/main/nicegui/outbox.py"
click node_frontend "https://github.com/zauberzeug/nicegui/blob/main/nicegui/static/nicegui.js"
click node_query "https://github.com/zauberzeug/nicegui/blob/main/nicegui/elements/query.js"
click node_binding "https://github.com/zauberzeug/nicegui/blob/main/nicegui/binding.py"
click node_timers "https://github.com/zauberzeug/nicegui/blob/main/nicegui/timer.py"
click node_storage "https://github.com/zauberzeug/nicegui/blob/main/nicegui/storage.py"
click node_persistence "https://github.com/zauberzeug/nicegui/tree/main/nicegui/persistence"
click node_custom_routes "https://github.com/zauberzeug/nicegui/blob/main/nicegui/app/app.py"
click node_native "https://github.com/zauberzeug/nicegui/tree/main/nicegui/native"
click node_native_events "https://github.com/zauberzeug/nicegui/blob/main/nicegui/native/event_manager.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_ui_api,node_pages,node_elements,node_highlevel,node_browser toneBlue
class node_app,node_server,node_client,node_element_core,node_events,node_outbox toneAmber
class node_frontend,node_query toneMint
class node_binding,node_timers,node_storage,node_persistence,node_custom_routes,node_native,node_native_events toneRose
class node_developer toneIndigo
```

## Components

### Python authoring

- [UI API](https://github.com/zauberzeug/nicegui/blob/main/nicegui/ui.py): `nicegui/ui.py`
- [Pages and routes](https://github.com/zauberzeug/nicegui/blob/main/nicegui/page.py): `nicegui/page.py`
- [UI elements](https://github.com/zauberzeug/nicegui/tree/main/nicegui/elements): `nicegui/elements`
- [Visualizations and media](https://github.com/zauberzeug/nicegui/tree/main/nicegui/elements): `nicegui/elements`

### Application runtime

- [App lifecycle](https://github.com/zauberzeug/nicegui/blob/main/nicegui/app/app.py): `nicegui/app/app.py`
- [ASGI server](https://github.com/zauberzeug/nicegui/blob/main/nicegui/server.py): `nicegui/server.py`
- [Client rendering](https://github.com/zauberzeug/nicegui/blob/main/nicegui/client.py): `nicegui/client.py`
- [Element model](https://github.com/zauberzeug/nicegui/blob/main/nicegui/element.py): `nicegui/element.py`
- [Event dispatch](https://github.com/zauberzeug/nicegui/blob/main/nicegui/events.py): `nicegui/events.py`
- [Client updates](https://github.com/zauberzeug/nicegui/blob/main/nicegui/outbox.py): `nicegui/outbox.py`

### Browser interface

- [Vue and Quasar UI](https://github.com/zauberzeug/nicegui/blob/main/nicegui/static/nicegui.js): `nicegui/static/nicegui.js`
- [DOM querying](https://github.com/zauberzeug/nicegui/blob/main/nicegui/elements/query.js): `nicegui/elements/query.js`

### State and extensions

- [Binding and refresh](https://github.com/zauberzeug/nicegui/blob/main/nicegui/binding.py): `nicegui/binding.py`
- [Timers](https://github.com/zauberzeug/nicegui/blob/main/nicegui/timer.py): `nicegui/timer.py`
- [Per-user persistence](https://github.com/zauberzeug/nicegui/blob/main/nicegui/storage.py): `nicegui/storage.py`
- [Persistence backends](https://github.com/zauberzeug/nicegui/tree/main/nicegui/persistence): `nicegui/persistence`
- [Custom data routes](https://github.com/zauberzeug/nicegui/blob/main/nicegui/app/app.py): `nicegui/app/app.py`
- [Native window mode](https://github.com/zauberzeug/nicegui/tree/main/nicegui/native): `nicegui/native`
- [Native event manager](https://github.com/zauberzeug/nicegui/blob/main/nicegui/native/event_manager.py): `nicegui/native/event_manager.py`

### Other components

- **App developer**
- **Browser user**

## Connections

- App developer → UI API: declares interface
- UI API → Pages and routes: registers pages
- UI API → UI elements: creates elements
- UI API → Visualizations and media: creates components
- UI API → App lifecycle: configures runtime
- Pages and routes → Client rendering: builds page
- UI elements → Element model: uses model
- Visualizations and media → Element model: uses model
- App lifecycle → ASGI server: starts server
- ASGI server → App lifecycle: serves requests
- Client rendering → Element model: serializes elements
- Client rendering → Browser user: serves interface
- Browser user → Vue and Quasar UI: uses interface
- Vue and Quasar UI → Client rendering: sends events
- Client rendering → Event dispatch: dispatches events
- Event dispatch → UI elements: invokes handlers
- UI elements → Client updates: queues updates
- Client updates → Vue and Quasar UI: sends updates
- DOM querying → Browser user: updates DOM
- Binding and refresh → UI elements: refreshes values
- Timers → UI elements: triggers updates
- Per-user persistence → Persistence backends: uses backend
- App lifecycle → Per-user persistence: owns storage
- Custom data routes → Browser user: serves responses
- App lifecycle → Native window mode: configures window
- Native event manager → Event dispatch: dispatches handlers