NiceGUI

To stream data from a ZeroMQ socket into a NiceGUI application, use the zmq.async library. This allows the ZeroMQ subscriber to operate within the asyncio event loop required by the NiceGUI server.

In this pattern, a ZeroMQ publisher (e.g., zmq-server.py) sends data to a socket, and a NiceGUI client (e.g., main.py) uses an asynchronous subscriber to receive that data and update UI elements like plots in real-time.

# Conceptual pattern for integration
import zmq.asyncio

# Use zmq.async to create a subscriber compatible with NiceGUI's asyncio loop
ctx = zmq.asyncio.Context()
subscriber = ctx.socket(zmq.SUB)
# ... subscribe and update NiceGUI components ...

NiceGUI does not use a virtual DOM. When you delete and recreate elements, the framework destroys the corresponding Vue components on the client. This causes the loss of focus, scroll position, animations, and client-side state.

Best Practices:

• For simple value changes: Update elements in place using .set_text(), .set_value(), or via bindings instead of clearing a container and recreating elements.
• For complex updates: Use @ui.refreshable to handle clearing and rebuilding specific subtrees safely.

# BAD: destroys and recreates on every data change
def show_count():
    container.clear()
    ui.label(f'Count: {count}')

# GOOD: updates the existing element in place
label = ui.label('Count: 0')
# then: label.set_text(f'Count: {count}') or bind_text_from

To create a custom UI element in NiceGUI based on an NPM module (like signature_pad), you follow a pattern of wrapping the JavaScript module in a custom element definition.

1. Define the JavaScript side: Create a .js file (e.g., signature_pad.js) that interfaces with the NPM module and a .py file (e.g., signature_pad.py) that defines the NiceGUI component class.
2. Bundle the module: Use a bundler like rollup to minify the module and place the output in a dist directory. The entry point (e.g., src/index.mjs) typically re-exports the module.
3. Integrate in Python: Import the custom component in your main.py to use it within your NiceGUI layout.

A function decorated with @ui.page runs exactly once when a user navigates to that route to build the initial page structure. It is not re-executed when the state changes.

To update the UI after the initial page load, you must use one of the following:

• Bindings: Automatic synchronization between Python attributes and UI elements.
• @ui.refreshable: Explicitly rebuilding a specific part of the UI.
• Direct mutation: Calling methods like .set_text(), .set_value(), or changing properties like .visible = False.
• Timers: Using ui.timer() to trigger updates periodically.

NiceGUI bindings use two mechanisms to keep Python and the UI in sync:

1. Push (Synchronous): When you assign a value to a BindableProperty (the descriptor used by attributes like value, text, or visible), the change propagates immediately through all linked bindings.
2. Pull (Asynchronous): A background refresh loop runs every binding_refresh_interval (default 0.1s) to check active_links. This allows bindings to work against plain Python objects (like dict keys or standard class attributes) that do not have built-in setters.

Key takeaways:

• Binding between two NiceGUI elements is synchronous.
• Binding to a plain dataclass or object attribute is subject to the ~100ms refresh interval.
• You generally do not need to call .update() after a bound assignment.

NiceGUI uses a thread-local slot stack to manage element hierarchy via Python context managers (with blocks).

• with element: pushes that element's default slot onto the stack.
• Any element created inside that with block is automatically registered as a child of that element.
• __exit__ pops the slot off the stack.

Crucial Rule: Element creation order matters. You cannot place an element into a parent after it has already been created unless you enter that parent's context using a with block.

row = ui.row()
# Too late to add to row here without entering its context:
with row:
    ui.label('This works')
# ui.label('This would go to page root, NOT inside row')