NiceGUI

https://nicegui.io/documentation
Admin
NiceGUI is a Python-based UI framework for building web applications with a wide range of...
Tokens:448,434
Snippets:2,891
Trust Score:9
Update:5 days ago
Show doc for...
Tokens:
Raw
### Create virtual environment and install dependencies

Source: https://nicegui.io/documentation/section_configuration_deployment

Commands to set up a Python virtual environment and install NiceGUI and PyInstaller. Run these before packaging.

```bash
python -m venv venv
source venv/bin/activate
pip install nicegui
pip install pyinstaller

```

--------------------------------

### app.on_startup

Source: https://nicegui.io/documentation/section_action_events

Registers a function to be called when NiceGUI is started or restarted.

```APIDOC
## app.on_startup

### Description
Registers a synchronous or asynchronous function to be called when NiceGUI is started or restarted.

### Method
N/A (event registration)

### Parameters
- **handler** (callable) - Required - The function to be called on startup.

### Request Example
```python
app.on_startup(my_startup_handler)
```

### Response
No response.
```

--------------------------------

### Run NiceGUI app with custom title

Source: https://nicegui.io/documentation/run

Minimal example that creates a label and starts the app with a custom page title using ui.run(title='My App').

```python
from nicegui import ui

ui.label('page with custom title')

ui.run(title='My App')

```

--------------------------------

### ui.run()

Source: https://nicegui.io/documentation/run

Starts the NiceGUI application server with optional configuration parameters. Most parameters only apply after a full restart and do not apply with auto-reloading.

```APIDOC
## ui.run()

### Description
Starts the NiceGUI application server with optional configuration parameters. Most parameters only apply after a full restart and do not apply with auto-reloading.

### Method
Function call

### Endpoint
ui.run()

### Parameters
- **root** (function) - Optional - Root page function (added in version 3.0.0).
- **host** (str) - Optional - Start server with this host (defaults to '127.0.0.1' in native mode, otherwise '0.0.0.0').
- **port** (int) - Optional - Use this port (default: 8080 in normal mode, and an automatically determined open port in native mode).
- **title** (str) - Optional - Page title (default: 'NiceGUI', can be overwritten per page).
- **viewport** (str) - Optional - Page meta viewport content (default: 'width=device-width, initial-scale=1', can be overwritten per page).
- **favicon** (str) - Optional - Path to a local image file, absolute http(s):// URL, data URL, inline SVG or emoji (e.g. '🚀', works for most browsers; default: None, NiceGUI icon will be used). In Windows native mode, a local .ico file path is also applied as the native window icon.
- **dark** (bool) - Optional - Whether to use Quasar's dark mode (default: False, use None for "auto" mode).
- **language** (str) - Optional - Language for Quasar elements and the `lang` attribute of the `html` tag (default: `None`, in which case Quasar elements use `'en-US'` and the `lang` attribute is omitted, updated in version 3.14.0).
- **binding_refresh_interval** (float) - Optional - Interval for updating active links (default: 0.1 seconds, bigger is more CPU friendly, since version 3.4.0: can be `None` to disable update loop).
- **reconnect_timeout** (float) - Optional - Maximum time the server waits for the browser to reconnect (default: 3.0 seconds).
- **message_history_length** (int) - Optional - Maximum number of messages that will be stored and resent after a connection interruption (default: 1000, use 0 to disable, added in version 2.9.0).
- **cache_control_directives** (str) - Optional - Cache control directives for internal static files (default: 'public, max-age=31536000, immutable, stale-while-revalidate=31536000').
- **gzip_middleware_factory** (callable) - Optional - GZipMiddleware factory function (e.g. `lambda app: GZipMiddleware(app, minimum_size=500, compresslevel=9)`, defaults to Starlette's `GZipMiddleware`, can be `None` to disable, added in version 3.5.0).
- **fastapi_docs** (bool or dict) - Optional - Enable FastAPI's automatic documentation with Swagger UI, ReDoc, and OpenAPI JSON (bool or dictionary as described here, default: False, updated in version 2.9.0).
- **show** (bool or str) - Optional - Automatically open the UI in a browser tab (default: True, opens "/", since version 3.6.0: you can pass a specific path like "/path/to/page").
- **on_air** (bool) - Optional - Tech preview: allows temporary remote access if set to True (default: disabled).
- **native** (bool) - Optional - Open the UI in a native window of size 800x600 (default: False, deactivates show, automatically finds an open port).
- **window_size** (tuple) - Optional - Open the UI in a native window with the provided size (e.g. (1024, 786), default: None, also activates native).
- **fullscreen** (bool) - Optional - Open the UI in a fullscreen window (default: False, also activates native).
- **frameless** (bool) - Optional - Open the UI in a frameless window (default: False, also activates native).
- **reload** (bool) - Optional - Automatically reload the UI on file changes (default: True).
- **uvicorn_logging_level** (str) - Optional - Logging level for uvicorn server (default: 'warning').
- **uvicorn_reload_dirs** (str) - Optional - String with comma-separated list for directories to be monitored (default is current working directory only).
- **uvicorn_reload_includes** (str) - Optional - String with comma-separated list of glob-patterns which trigger reload on modification (default: '*.py').
- **uvicorn_reload_excludes** (str) - Optional - String with comma-separated list of glob-patterns which should be ignored for reload (default: '.*, .py[cod], .sw.*, ~*').
- **tailwind** (bool) - Optional - Whether to use Tailwind CSS (experimental, default: True).
- **unocss** (str) - Optional - Use UnoCSS with the specified preset instead of Tailwind CSS (default: `None`, options: "mini", "wind3", "wind4", added in version 3.7.0).
- **prod_js** (bool) - Optional - Whether to use the production version of Vue and Quasar dependencies (default: True).
- **endpoint_documentation** (str) - Optional - Control what endpoints appear in the autogenerated OpenAPI docs (default: 'none', options: 'none', 'internal', 'page', 'all').
- **storage_secret** (str) - Optional - Secret key for browser-based storage (default: None, a value is required to enable ui.storage.user and ui.storage.browser).
- **session_middleware_kwargs** (dict) - Optional - Additional keyword arguments passed to SessionMiddleware that creates the session cookies used for browser-based storage.
- **show_welcome_message** (bool) - Optional - Whether to show the welcome message (default: True).
- **markdown** (bool) - Optional - Whether to serve a Markdown representation when a client sends `Accept: text/markdown` (experimental, default: False, can be overwritten per page, added in version 3.11.0).
- **kwargs** (dict) - Optional - Additional keyword arguments are passed to uvicorn.run.

### Request Example
```python
from nicegui import ui

ui.label('page with custom title')

ui.run(title='My App')
```

### Response
No return value documented.
```

--------------------------------

### Nuitka main.py with native window

Source: https://nicegui.io/documentation/section_configuration_deployment

Example main.py for Nuitka packaging. Uses native.find_open_port() and ui.run with reload=False.

```python
from nicegui import native, ui

def root():
    ui.label('Hello from Nuitka')

ui.run(root, reload=False, port=native.find_open_port())

```

--------------------------------

### on_start(callback) - Add start callback

Source: https://nicegui.io/documentation/joystick

Adds a callback to be invoked when the user touches the joystick. Returns the element for chaining.

```APIDOC
## on_start(callback)

### Description
Adds a callback to be invoked when the user touches the joystick.

### Parameters
- **callback** (Callable[[JoystickEventArguments], Any] | Callable[[], Any]) - Required - The callback function to invoke.

### Returns
- **Self** - The element instance for chaining.

```

--------------------------------

### Switch Example

Source: https://nicegui.io/documentation/section_controls

Creates a switch and binds the visibility of a label to its value. Based on Quasar's QToggle component.

```python
from nicegui import ui

switch = ui.switch('switch me')
ui.label('Switch!').bind_visibility_from(switch, 'value')

ui.run()

```

--------------------------------

### Basic ui.input_chips example

Source: https://nicegui.io/documentation/input_chips

Creates a chip input with an initial list of values. The label is 'My favorite chips' and the initial value is a list of three strings.

```python
from nicegui import ui

ui.input_chips('My favorite chips', value=['Pringles', 'Doritos', "Lay's"])

ui.run()

```

--------------------------------

### Screen fixture usage example

Source: https://nicegui.io/documentation/section_testing

Demonstrates the `screen` fixture for headless browser testing, using Selenium keys to navigate and interact with the application.

```python
from selenium.webdriver.common.keys import Keys

screen.open('/')
screen.type(Keys.TAB) # to focus on the first input
screen.type('user1')
screen.type(Keys.TAB) # to focus the second input
screen.type('pass1')
screen.click('Log in')
screen.should_contain('Hello user1!')
screen.click('logout')
screen.should_contain('Log in')
```

--------------------------------

### Slider Example

Source: https://nicegui.io/documentation/section_controls

Creates a slider with min, max, and initial value, and binds a label to display the current value. Based on Quasar's QSlider component.

```python
from nicegui import ui

slider = ui.slider(min=0, max=100, value=50)
ui.label().bind_text_from(slider, 'value')

ui.run()

```

--------------------------------

### Subscribe to the drag event

Source: https://nicegui.io/documentation/scene

Subscribes to the 'drag' event to get immediate updates during dragging. The example updates a box's position and size based on two draggable spheres.

```Python
from nicegui import events, ui

with ui.scene(width=285, drag_constraints='z=0') as scene:
    box = scene.box(1, 1, 0.2).move(0, 0).material('Orange')
    sphere1 = scene.sphere(0.2).move(0.5, -0.5).material('SteelBlue').draggable()
    sphere2 = scene.sphere(0.2).move(-0.5, 0.5).material('SteelBlue').draggable()

def handle_drag(e: events.GenericEventArguments) -> None:
    x1 = sphere1.x if e.args['object_id'] == sphere2.id else e.args['x']
    y1 = sphere1.y if e.args['object_id'] == sphere2.id else e.args['y']
    x2 = sphere2.x if e.args['object_id'] == sphere1.id else e.args['x']
    y2 = sphere2.y if e.args['object_id'] == sphere1.id else e.args['y']
    box.move((x1 + x2) / 2, (y1 + y2) / 2).scale(x2 - x1, y2 - y1, 1)
scene.on('drag', handle_drag)

ui.run()

```

--------------------------------

### Wait for map initialization with initialized

Source: https://nicegui.io/documentation/leaflet

Waits for the map to be initialized before running methods like fitBounds. The example creates a polygon layer, awaits the map's initialized method, gets the bounds of the polygon, and fits the map to those bounds.

```python
from nicegui import ui

@ui.page('/')
async def page():
    m = ui.leaflet(zoom=5)
    central_park = m.generic_layer(name='polygon', args=[[
        (40.767809, -73.981249),
        (40.800273, -73.958291),
        (40.797011, -73.949683),
        (40.764704, -73.973741),
    ]])
    await m.initialized()
    bounds = await central_park.run_method('getBounds')
    m.run_map_method('fitBounds', [[bounds['_southWest'], bounds['_northEast']]])

ui.run()

```

--------------------------------

### Configure native window before run (good_example.py)

Source: https://nicegui.io/documentation/section_configuration_deployment

Sets app.native.window_args before the main guard, which works because the native app runs in a separate process. Uses reload=False for packaged apps.

```python
from nicegui import app, ui

app.native.window_args['resizable'] = False  # works

if __name__ == '__main__':
    ui.run(native=True, reload=False)

```

--------------------------------

### Run async JavaScript with ui.run_javascript - get user location

Source: https://nicegui.io/documentation/run_javascript

Demonstrates running asynchronous JavaScript code in the browser using a Promise. The example retrieves the user's geolocation and returns latitude/longitude. Uses timeout=5.0 seconds. The response is awaited and used in a notification.

```python
from nicegui import ui

async def show_location():
    response = await ui.run_javascript('''
        return await new Promise((resolve, reject) => {
            if (!navigator.geolocation) {
                reject(new Error('Geolocation is not supported by your browser'));
            } else {
                navigator.geolocation.getCurrentPosition(
                    (position) => {
                        resolve({
                            latitude: position.coords.latitude,
                            longitude: position.coords.longitude,
                        });
                    },
                    () => {
                        reject(new Error('Unable to retrieve your location'));
                    }
                );
            }
        });
    ''', timeout=5.0)
    ui.notify(f'Your location is {response["latitude"]}, {response["longitude"]}')

ui.button('Show location', on_click=show_location)

ui.run()
```

--------------------------------

### app.native.start_args

Source: https://nicegui.io/documentation/section_configuration_deployment

Provides extra keyword arguments for the `webview.start` function. These arguments take precedence over parameters defined in `ui.run`.

```APIDOC
## app.native.start_args

### Description
Provides extra keyword arguments for the `webview.start` function. These arguments take precedence over parameters defined in `ui.run`.

### Method
N/A (attribute)

### Endpoint
N/A

### Parameters
#### Dictionary Keys
- **debug** (bool) - Optional - Whether to enable debug mode.

### Request Example
```python
app.native.start_args['debug'] = True
```

### Response
#### Success Response
N/A (modifies startup configuration)

#### Response Example
N/A
```

--------------------------------

### Create API endpoint with @app.get()

Source: https://nicegui.io/documentation/section_pages_routing

Implements a RESTful API endpoint using FastAPI's app object. The example defines a GET endpoint that returns a random number and a page that navigates to it. You can also return any FastAPI response object inside a page function, such as RedirectResponse.

```python
import random
from nicegui import app, ui

@app.get('/random/{max}')
def generate_random_number(max: int):
    return {'min': 0, 'max': max, 'value': random.randint(0, max)}

@ui.page('/')
def page():
    max = ui.number('max', value=100)
    ui.button('generate random number',
              on_click=lambda: ui.navigate.to(f'/random/{max.value:.0f}'))

ui.run()

```

--------------------------------

### Download file, URL, and content with ui.download

Source: https://nicegui.io/documentation/download

General example showing how to use ui.download.file, ui.download.from_url, and ui.download.content to trigger downloads of a local file, a relative URL, and raw content. Added in version 2.14.0.

```python
from nicegui import ui

ui.button('Local file', on_click=lambda: ui.download.file('main.py'))
ui.button('From URL', on_click=lambda: ui.download.from_url('/logo.png'))
ui.button('Content', on_click=lambda: ui.download.content('Hello World', 'hello.txt'))

ui.run()

```

--------------------------------

### Create a carousel with animated slides, arrows, and navigation

Source: https://nicegui.io/documentation/carousel

Creates a ui.carousel with animated transitions, arrows, and navigation dots enabled, and sets a fixed height of 180px via the 'height=180px' prop. Inside, three ui.carousel_slide elements each contain an image from picsum.photos. The example ends with ui.run() to start the NiceGUI application.

```Python
from nicegui import ui

with ui.carousel(animated=True, arrows=True, navigation=True).props('height=180px'):
    with ui.carousel_slide().classes('p-0'):
        ui.image('https://picsum.photos/id/30/270/180').classes('w-[270px]')
    with ui.carousel_slide().classes('p-0'):
        ui.image('https://picsum.photos/id/31/270/180').classes('w-[270px]')
    with ui.carousel_slide().classes('p-0'):
        ui.image('https://picsum.photos/id/32/270/180').classes('w-[270px]')

ui.run()

```

--------------------------------

### Overwrite Tailwind's default style for h2 elements

Source: https://nicegui.io/documentation/section_styling_appearance

Override Tailwind CSS's default styles by adding a style tag with type 'text/tailwindcss' via ui.add_head_html. Without this type, the style is evaluated too early and gets overwritten by Tailwind. The example sets the font size of h2 elements to 150%.

```python
from nicegui import ui

ui.add_head_html('''
    <style type="text/tailwindcss">
        h2 {
            font-size: 150%;
        }
    </style>
''')
ui.html('<h2>Hello world!</h2>', sanitize=False)

ui.run()

```

--------------------------------

### Create a Highchart with draggable points and event callbacks

Source: https://nicegui.io/documentation/highchart

This example creates a Highchart with two series and enables dragging points vertically. It uses the 'draggable-points' extra and defines callbacks for point click, drag start, and drop events. The point_index in events is internal to Highcharts and may differ from the position in options after updates; use explicit point ids or look up by point_x and point_y for stability.

```python
from nicegui import ui

ui.highchart(
    {
        'title': False,
        'plotOptions': {
            'series': {
                'stickyTracking': False,
                'dragDrop': {'draggableY': True, 'dragPrecisionY': 1},
            },
        },
        'series': [
            {'name': 'A', 'data': [[20, 10], [30, 20], [40, 30]]},
            {'name': 'B', 'data': [[50, 40], [60, 50], [70, 60]]},
        ],
    },
    extras=['draggable-points'],
    on_point_click=lambda e: ui.notify(f'Click: {e}'),
    on_point_drag_start=lambda e: ui.notify(f'Drag start: {e}'),
    on_point_drop=lambda e: ui.notify(f'Drop: {e}')
).classes('w-full h-64')

ui.run()

```

--------------------------------

### Main application file (app.py)

Source: https://nicegui.io/documentation/section_testing

Defines the main entry point for the NiceGUI application. The `root` function creates a button that triggers a notification. This file is used as the entry point for integration tests.

```python
from nicegui import ui

def root() -> None:
    ui.button('Click me', on_click=lambda: ui.notify('Hello World!'))

ui.run(root)
```

--------------------------------

### Create a popup with a bound label and input (main.py)

Source: https://nicegui.io/documentation/popup

Shows how to create a popup that opens when clicking a label. The label text is bound to the client storage 'name', and the popup contains an input that is also bound to the same storage key. Pressing Enter closes the popup. Requires app.storage.client to be initialized.

```python
from nicegui import app, ui

app.storage.client['name'] = 'NiceGUI User'

with ui.label().bind_text_from(app.storage.client, 'name').classes('cursor-pointer'):
    with ui.popup() as popup:
        ui.input().props('autofocus') \
            .bind_value(app.storage.client, 'name') \
            .on('keydown.enter', popup.close)

ui.run()

```

--------------------------------

### Filter by markers

Source: https://nicegui.io/documentation/element_filter

Demonstrates filtering elements by markers. Elements with marker 'red' get a red background, 'strong' get bold text, and 'red strong' get both red background and white text.

```python
from nicegui import ElementFilter, ui

with ui.card().mark('red'):
    ui.label('label A')
with ui.card().mark('strong'):
    ui.label('label B')
with ui.card().mark('red strong'):
    ui.label('label C')

ElementFilter(marker='red').classes('bg-red-200')
ElementFilter(marker='strong').classes('text-bold')
ElementFilter(marker='red strong').classes('bg-red-600 text-white')

ui.run()

```

--------------------------------

### Rendered output of ui.code example

Source: https://nicegui.io/documentation/code

The displayed output of the ui.code example, showing the code block as rendered on localhost:8080.

```python
from nicegui import ui

ui.label('Code inception!')

ui.run()

```

--------------------------------

### Create a page with header, footer, drawers, sticky button, and scroll-to-top button

Source: https://nicegui.io/documentation/page_layout

This example creates a page with a header, footer, left and right drawers, a sticky button, and a scroll-to-top button. The right drawer is toggled by a button in the header. The page is linked from the root page.

```python
from nicegui import ui

@ui.page('/page_layout')
def page_layout():
    ui.label('CONTENT')
    [ui.label(f'Line {i}') for i in range(100)]
    with ui.header(elevated=True).style('background-color: #3874c8').classes('items-center justify-between'):
        ui.label('HEADER')
        ui.button(on_click=lambda: right_drawer.toggle(), icon='menu').props('flat color=white')
    with ui.left_drawer(top_corner=True, bottom_corner=True).style('background-color: #d7e3f4'):
        ui.label('LEFT DRAWER')
    with ui.right_drawer(fixed=False).style('background-color: #ebf1fa').props('bordered') as right_drawer:
        ui.label('RIGHT DRAWER')
    with ui.footer().style('background-color: #3874c8'):
        ui.label('FOOTER')
    with ui.page_sticky(position='bottom-left', x_offset=20, y_offset=20):
        ui.button('Sticky Button', on_click=lambda: ui.notify('Sticky Button Clicked'))
    with ui.page_scroller(position='bottom-right', x_offset=20, y_offset=20):
        ui.button('Scroll to Top')

@ui.page('/')
def page():
    ui.link('show page with fancy layout', page_layout)

ui.run()

```

--------------------------------

### Minimal main.py for nicegui-pack

Source: https://nicegui.io/documentation/section_configuration_deployment

Define a root page function and call ui.run with reload=False and a free port. This is required for packaging with nicegui-pack.

```python
from nicegui import native, ui

def root():
    ui.label('Hello from PyInstaller')

ui.run(root, reload=False, port=native.find_open_port())

```

--------------------------------

### AG Grid with Conditional Cell Formatting

Source: https://nicegui.io/documentation/aggrid

Uses 'cellClassRules' to conditionally format cells based on their values. Cells with values less than 21 get 'bg-red-300', and values greater than or equal to 21 get 'bg-green-300'.

```Python
from nicegui import ui

ui.aggrid({
    'columnDefs': [
        {'headerName': 'Name', 'field': 'name'},
        {'headerName': 'Age', 'field': 'age', 'cellClassRules': {
            'bg-red-300': 'x < 21',
            'bg-green-300': 'x >= 21',
        }},
    ],
    'rowData': [
        {'name': 'Alice', 'age': 18},
        {'name': 'Bob', 'age': 21},
        {'name': 'Carol', 'age': 42},
    ],
})

ui.run()
```

--------------------------------

### FileUpload.size()

Source: https://nicegui.io/documentation/upload

Gets the file size in bytes.

```APIDOC
## FileUpload.size()

### Description
Gets the file size in bytes.

### Method
size

### Returns
int
```

--------------------------------

### Incorrect configuration placement (bad_example.py)

Source: https://nicegui.io/documentation/section_configuration_deployment

Sets app.native.window_args inside the main guard, which is ignored because the native app runs in a separate process. Shows the non-working configuration.

```python
from nicegui import app, ui

if __name__ == '__main__':
    app.native.window_args['resizable'] = False  # ignored

    ui.run(native=True, reload=False)

```

--------------------------------

### User storage example (main.py)

Source: https://nicegui.io/documentation/section_action_events

Example of using app.storage.user to count page visits. Requires storage_secret to secure the browser session cookie. Note: user storage persists across server restarts and page reloads, but needs serializable data.

```python
from nicegui import app, ui

@ui.page('/')
def index():
    app.storage.user['count'] = app.storage.user.get('count', 0) + 1
    with ui.row():
       ui.label('your own page visits:')
       ui.label().bind_text_from(app.storage.user, 'count')

ui.run(storage_secret='private key to secure the browser session cookie')

```

--------------------------------

### Create a basic label with ui.label

Source: https://nicegui.io/documentation/label

Creates a simple label with the text 'some label' and runs the NiceGUI application. The label is displayed at localhost:8080.

```python
from nicegui import ui

ui.label('some label')

ui.run()

```

--------------------------------

### Run JSON editor methods (expand, collapse, get)

Source: https://nicegui.io/documentation/json_editor

Demonstrates using run_editor_method to call editor methods. The colon prefix in ':expand' indicates a JavaScript expression evaluated on the client. Includes buttons for expand, collapse, readonly, and getting data asynchronously.

```python
from nicegui import ui

json = {
    'Name': 'Alice',
    'Age': 42,
    'Address': {
        'Street': 'Main Street',
        'City': 'Wonderland',
    },
}
editor = ui.json_editor({'content': {'json': json}})

ui.button('Expand', on_click=lambda: editor.run_editor_method(':expand', '[]', 'path => true'))
ui.button('Collapse', on_click=lambda: editor.run_editor_method('collapse', []))
ui.button('Readonly', on_click=lambda: editor.run_editor_method('updateProps', {'readOnly': True}))

async def get_data() -> None:
    data = await editor.run_editor_method('get')
    ui.notify(data)
ui.button('Get Data', on_click=get_data)

ui.run()

```

--------------------------------

### Run nicegui-pack to create executable

Source: https://nicegui.io/documentation/section_configuration_deployment

This command creates a single-file executable named 'myapp' in the dist folder. It must be run after preparing main.py with reload=False and a root page function.

```bash
nicegui-pack --onefile --name "myapp" main.py

```

--------------------------------

### get_selected_rows

Source: https://nicegui.io/documentation/aggrid

Gets the currently selected rows. Especially useful when the grid is configured with `rowSelection: 'multiple'`.

```APIDOC
## get_selected_rows

### Description
Get the currently selected rows. This method is especially useful when the grid is configured with `rowSelection: 'multiple'`. See AG Grid API for more information.

### Method
Instance method

### Signature
`get_selected_rows() -> list[dict]`

### Returns
- list of selected row data
```

--------------------------------

### activate()

Source: https://nicegui.io/documentation/timer

Activates the timer element. This method is used to start or resume the timer's functionality.

```APIDOC
## activate()

### Description
Activates the timer element.

### Method
activate

### Signature
`activate() -> None`

### Parameters
None

### Returns
None
```

--------------------------------

### Create a Table with ui.table

Source: https://nicegui.io/documentation/section_data_elements

Defines columns and rows for a table, sets row_key to 'name', and runs the NiceGUI app. The table displays the data with sorting and required column features.

```python
from nicegui import ui

columns = [
    {'name': 'name', 'label': 'Name', 'field': 'name', 'required': True, 'align': 'left'},
    {'name': 'age', 'label': 'Age', 'field': 'age', 'sortable': True},
]
rows = [
    {'name': 'Alice', 'age': 18},
    {'name': 'Bob', 'age': 21},
    {'name': 'Carol'},
]
ui.table(columns=columns, rows=rows, row_key='name')

ui.run()

```

--------------------------------

### get_selected_row

Source: https://nicegui.io/documentation/aggrid

Gets the single currently selected row. Especially useful when the grid is configured with `rowSelection: 'single'`.

```APIDOC
## get_selected_row

### Description
Get the single currently selected row. This method is especially useful when the grid is configured with `rowSelection: 'single'`.

### Method
Instance method

### Signature
`get_selected_row() -> dict | None`

### Returns
- Row data of the first selection if any row is selected, otherwise None
```

--------------------------------

### ui.audio Initializer

Source: https://nicegui.io/documentation/audio

Creates an audio element with the specified source and playback options.

```APIDOC
## ui.audio Initializer

### Description
Creates an audio player element.

### Parameters
- **src** (str) - Required - URL or local file path of the audio source
- **controls** (bool) - Optional - Whether to show the audio controls (default: True)
- **autoplay** (bool) - Optional - Whether to start playing automatically (default: False)
- **muted** (bool) - Optional - Whether the audio should be initially muted (default: False)
- **loop** (bool) - Optional - Whether the audio should loop (default: False)

### Example
```python
from nicegui import ui

a = ui.audio('https://example.com/audio.mp3')
```
```

--------------------------------

### ui.run(native=True, window_size=(400, 300), fullscreen=False)

Source: https://nicegui.io/documentation/section_configuration_deployment

Enables native mode for NiceGUI, allowing the app to run in a native window. Customize the initial window size and display mode using the `window_size` and `fullscreen` parameters.

```APIDOC
## ui.run

### Description
Enables native mode for NiceGUI, allowing the app to run in a native window. Customize the initial window size and display mode using the `window_size` and `fullscreen` parameters.

### Method
N/A (Python function)

### Endpoint
N/A

### Parameters
#### Function Parameters
- **native** (bool) - Required - Set to `True` to enable native mode.
- **window_size** (tuple) - Optional - Initial window size as a tuple of (width, height).
- **fullscreen** (bool) - Optional - Set to `True` to start in fullscreen mode.

### Request Example
```python
ui.run(native=True, window_size=(400, 300), fullscreen=False)
```

### Response
#### Success Response
N/A (starts the application)

#### Response Example
N/A
```

--------------------------------

### UI code for ElementFilter example

Source: https://nicegui.io/documentation/user

Creates three labels with the marker 'number' to be used with ElementFilter in the user assertions.

```python
ui.label('1').mark('number')
ui.label('2').mark('number')
ui.label('3').mark('number')

```

--------------------------------

### Using the screen fixture to test login flow

Source: https://nicegui.io/documentation/screen

Shows how to use the `screen` fixture to interact with a page: open the root URL, type into inputs using TAB to focus, click a button, and assert content. The example logs in as 'user1' and then logs out.

```python
from selenium.webdriver.common.keys import Keys

screen.open('/')
screen.type(Keys.TAB) # to focus on the first input
screen.type('user1')
screen.type(Keys.TAB) # to focus the second input
screen.type('pass1')
screen.click('Log in')
screen.should_contain('Hello user1!')
screen.click('logout')
screen.should_contain('Log in')

```

--------------------------------

### Large datasets with Plotly

Source: https://nicegui.io/documentation/plotly

Example of using NumPy arrays with Plotly in NiceGUI to handle large datasets efficiently.

```APIDOC
## Large datasets with Plotly

### Description
When plotting a large number of data points, pass NumPy arrays (or pandas Series) to Plotly rather than Python lists, and avoid converting them back with `.tolist()`. For NumPy arrays, Plotly uses a compact binary encoding (base64-encoded typed arrays) that makes the payload roughly half the size — far less data to transfer, parse and keep in memory — which is what avoids freezing the UI on large updates. This requires Plotly 6.0 or newer, where the binary encoding is the default.

### Example
```python
import numpy as np
import plotly.graph_objects as go
from nicegui import ui

x = np.linspace(0, 10, 100_000)
y = np.sin(x) + np.random.normal(0, 0.1, x.size)
fig = go.Figure(go.Scattergl(x=x, y=y, mode='markers', marker=dict(size=2)))
fig.update_layout(margin=dict(l=0, r=0, t=0, b=0))
ui.plotly(fig).classes('w-full h-40')

ui.run()
```
```

--------------------------------

### Interactive styling playground for NiceGUI elements

Source: https://nicegui.io/documentation/section_styling_appearance

Provides an interactive example where users can select a NiceGUI element and apply Tailwind classes, Quasar props, and CSS styles to see the effects. The code creates a button and allows dynamic styling.

```python
from nicegui import ui

element = ui.button('element')


```

```python
ui.run()

```

--------------------------------

### get_client_data

Source: https://nicegui.io/documentation/aggrid

Gets the data from the client including any edits made by the client. Especially useful when the grid is configured with `'editable': True`.

```APIDOC
## get_client_data

### Description
Get the data from the client including any edits made by the client. This method is especially useful when the grid is configured with `'editable': True`. See AG Grid API for more information. Note that when editing a cell, the row data is not updated until the cell exits the edit mode. This does not happen when the cell loses focus, unless `stopEditingWhenCellsLoseFocus: True` is set.

### Method
Instance method

### Signature
`get_client_data(timeout: float = 1, method: Literal['all_unsorted', 'filtered_unsorted', 'filtered_sorted', 'leaf'] = 'all_unsorted') -> list[dict]`

### Parameters
- **timeout** (float) - Optional - Timeout in seconds (default: 1 second)
- **method** (Literal['all_unsorted', 'filtered_unsorted', 'filtered_sorted', 'leaf']) - Optional - Method to access the data, "all_unsorted" (default), "filtered_unsorted", "filtered_sorted", "leaf"

### Returns
- list of row data
```

--------------------------------

### Run NiceGUI app in Docker container

Source: https://nicegui.io/documentation/section_configuration_deployment

Launches main.py from the current directory on port 80 using the pre-built zauberzeug/nicegui:latest image. The -p 80:8080 flag maps the container's port 8080 to the host's port 80, and the volume mounts the current directory to /app/. The -e PUID and -e PGID set the user and group IDs.

```bash
docker run -it --restart always \
    -p 80:8080 \
    -e PUID=$(id -u) \
    -e PGID=$(id -g) \
    -v $(pwd)/:/app/ \
    zauberzeug/nicegui:latest

```
Tokens:
Raw