Managing state

[FabianGoessling]

Hey there,

i am using nicegui for almost three years now, but am still struggling with properly managing my application state in a clean and concise way.

Prior to using nicegui I was building the frontend using vue.js and the backend using fastapi/Django. The split between frontend and backend of course made coding way more complicated but I was always sure where my variables "lived" - some in my vue.js data prop and some in the backend.

Using nicegui my code always ends up in a situation where I cannot use the backend without frontend and vice versa. This contradicts the idea that my backend is setup as an API, which should be usable (and testable) standalone.

Recently I read the documentation of reflex.dev and they are very clear on the matter of the application state. They have a state class which lives in the backend side and is automatically refreshed/bound.

How would i manage state best in your opinion? How are you doing it for larger apps? Can I adopt the reflex pattern with nicegui or is there a conceptional difference?

Moreover I am wondering if there is a possibility to create variables which are only on the frontend side (e.g. an "is_visible" or an "is_calculating"). Is it possible or are all variables always updated in the backend?

Looking forward to your approaches,

Thanks
Fabian

[evnchn]

Hello @FabianGoessling. Let me help you as much as possible in getting over the NiceGUI learning curve.

---

First of all, unlike Reflex, our front-end and back-end is much more "close together". Our page functions BOTH does back-end calculations, as well as populating the front-end with ui.xxx elements.

This is an important realization to make. This is because, if I am not mistaken, in Reflex, you're not supposed to return UI elements in yout class MyStateClass(rx.State):, and you are also not supposed to do calculation while you are in the middle of defining the rx.vstack.

However, in NiceGUI, you can imagine each page as one Python function, which just so happens to have some ui.xxx which spawns some UI elements. You can call them dynamically with parameters depending on Python calculation result, or selective not at all if you want.

So, in short, I'd say Reflex does full-stack by having you be both a front-end and a back-end engineer, while NiceGUI let any browser be the frontend of your Python code while you focus on the backend only.

---

From what I see, 3 choices:

1. If they are stuff you initialize always, the you can put them in the page definition

@ui.page('/hello')
def hello_page():
    hello_string = generate_hello_string() # see wht I did here
    ui.label(hello_string)

This way, on every page load, the string is loaded in

2. If they are stuff for which you need the UI to stay in sync, the app.storage.general / app.storage.user is my go-to

from nicegui import ui, app

app.storage.general['hello_string'] = generate_hello_string() # see wht I did here

@ui.page('/hello')
def hello_page():
    ui.label().bind_text_from(app.storage.general, 'hello_string') # see wht I did here

3. Otherwise, since we are executing native Python code in the frontend-backend all-inclusive page function (this sets us apart from Reflex IMO) we can easily fetch from some external source on every page load

from nicegui import ui, app

@ui.page('/hello')
def hello_page():
    ui.input(load_from_SQLite(), on_change=lambda e: save_to_SQLite(e.value))

---

However, you need to be more specific for me to provide any more specific recommendations.

If you don't mind, you can open-source your application, then me and others will raise issues and PRs if I have spare time. You may even get featured on the NiceGUI examples!

Alternatively, if you'd like not to do that, you would need to boil-down your code to only the problematic parts and provide a MRE. https://github.com/zauberzeug/nicegui/wiki/FAQs#why-is-it-important-to-provide-a-minimal-reproducible-example

[buiapp]

Hey @FabianGoessling,

I stumbled upon your discussion about state management in NiceGUI, and I thought my library reaktiv might help with this issue.

I'm not a NiceGUI expert by any means, but I have extensive experience with Angular and similar reactive frameworks. When I faced similar state management challenges in my Python applications, I ended up creating reaktiv - which is essentially an Angular Signals port to Python. The reactive pattern it implements is similar to what you'll find in SolidJS, Vue.js, and React.

Here's how I've been using it with NiceGUI in my internal tools:

# install reaktiv with `pip install reaktiv`
from reaktiv import Signal, Computed, Effect
from nicegui import ui

# State module - completely independent from UI
class TodoState:
    def __init__(self):
        self.todos = Signal([])
        self.filter = Signal("all")  # all, active, completed
        
        self.filtered_todos = Computed(lambda: [
            todo for todo in self.todos()
            if self.filter() == "all" 
            or (self.filter() == "active" and not todo["completed"])
            or (self.filter() == "completed" and todo["completed"])
        ])
        self.active_count = Computed(lambda: 
            sum(1 for todo in self.todos() if not todo["completed"])
        )
        self.completed_count = Computed(lambda: 
            sum(1 for todo in self.todos() if todo["completed"])
        )
    
    def add_todo(self, text):
        self.todos.update(lambda todos: todos + [{"text": text, "completed": False}])
    
    def toggle_todo(self, index):
        self.todos.update(lambda todos: [
            {**todo, "completed": not todo["completed"]} if i == index else todo
            for i, todo in enumerate(todos)
        ])
    
    def clear_completed(self):
        self.todos.update(lambda todos: [todo for todo in todos if not todo["completed"]])

# Create a state instance
state = TodoState()

# UI layer can now use the state
with ui.card():
    ui.label("Todo App").classes("text-xl")
    
    # Input for new todos
    with ui.row():
        new_todo = ui.input("New task")
        ui.button("Add", on_click=lambda: [state.add_todo(new_todo.value), new_todo.set_value("")])
    
    # Todo list - connected to state via Effect
    todo_container = ui.column()
    
    def render_todos():
        todo_container.clear()
        for i, todo in enumerate(state.filtered_todos()):
            with todo_container:
                with ui.row():
                    ui.checkbox(value=todo["completed"], on_change=lambda e, idx=i: state.toggle_todo(idx))
                    ui.label(todo["text"]).classes("line-through" if todo["completed"] else "")
    
    # Effect connects state to UI
    render_effect = Effect(render_todos)
    
    # Filter controls
    with ui.row():
        ui.button("All", on_click=lambda: state.filter.set("all"))
        ui.button("Active", on_click=lambda: state.filter.set("active"))
        ui.button("Completed", on_click=lambda: state.filter.set("completed"))
        ui.button("Clear completed", on_click=lambda: state.clear_completed())
    
    # Status display - automatically updates
    status_label = ui.label()
    status_effect = Effect(lambda: status_label.set_text(
        f"{state.active_count()} active, {state.completed_count()} completed"
    ))

ui.run()

What I love about this approach is that I've completely separated my state logic from the UI.

I hope this will be interesting for some people.

[buiapp]

Your approach of separating backend and frontend state is definitely on the right track. That's often the first step toward a cleaner architecture, and you've already made good progress there.

I think one of the core challenges you might be facing (which wasn't explicitly mentioned but is common in this setup) is keeping your backend and frontend states properly synchronized.

In your current setup, you might have something like this happening:

# When user selects an option in the dropdown
def on_select_change(e):
    # 1. Update the backend state
    backend_state.selected_option = e.value
    
    # 2. Maybe trigger some business logic
    update_derived_data_based_on_selection()
    
    # 3. Update UI elements that depend on this selection
    update_related_ui_elements()
    
    # 4. If the business logic changed other backend state, sync that too
    if backend_state.something_else_changed:
        update_even_more_ui_elements()

This pattern becomes increasingly difficult to maintain as your application grows. You need to remember which components depend on which state, and manually orchestrate all the updates.

With reaktiv, this synchronization becomes automatic through the reactive system:

from reaktiv import Signal, Computed, Effect
from nicegui import ui

# Backend state
class BackendState:
    def __init__(self):
        # Primary state
        self.selected_option = Signal("A")
        self.available_options = Signal(["A", "B", "C"])
        
        # Derived state using Computed
        self.option_details = Computed(lambda: self._get_option_details(self.selected_option()))
        
    def _get_option_details(self, option):
        # Business logic to fetch details for an option
        return {"name": option, "description": f"Option {option} details"}

# Frontend state
class FrontendState:
    def __init__(self):
        self.dialog_is_open = Signal(False)

# Create instances
backend = BackendState()
frontend = FrontendState()

# UI Component
def setup_option_selector():
    # Create the select element
    select = ui.select(options=backend.available_options())
    
    # Connect UI → Backend (when select changes)
    def on_select_change(e):
        backend.selected_option.set(e.value)
    select.on_value_change(on_select_change)
    
    # Connect Backend → UI (when signal changes)
    def update_select_from_signal():
        select.value = backend.selected_option()
    # Keep a reference to prevent garbage collection
    select._effect = Effect(update_select_from_signal)
    
    # Additional UI that depends on selection
    details_label = ui.label()
    # This will automatically update whenever option_details changes
    # Effect must be retained through assigning to a variable. In production, assigning to `self` would be better.
    details_label._effect = Effect(lambda: details_label.set_text(
        f"Details: {backend.option_details()['description']}"
    ))

Regarding the websocket "ping-pong" you mentioned: I think that this can't be completely eliminated because it's inherent to how NiceGUI works. NiceGUI's architecture relies on websockets to communicate between the Python backend and the browser frontend.

When a UI event happens, it sends a websocket message to Python. When Python changes state, it sends websocket messages back to update the UI. This bidirectional communication is fundamental to NiceGUI's design. (Please correct me @evnchn if I am wrong here.)

[evnchn]

Demo integration blocked until buiapp/reaktiv#27 is resolved.

[phifuh]

🗡️ I am not sure if i feel stupid but in my current project I used pub/sub pattern mixed with some global single storage to fix this.
Using the elements id to track the path to have some sort of "cache" that only the specific children needs to be updated

[evnchn]

Sounds like genius to me though. Do you mind to share the source?

[phifuh]

@evnchn

Sharing everything would probably be overkill, but I can give you a quick rundown.

We have:

• Templates, which can have 1–M panels
• Panels can have 1–M containers
• Containers can have 1–M subcontainers
• Containers/Subcontainers can have 1–M components

Panels is the box, where we can but containers inside, and all components are ui.elements() like an ui.input()

They are created using a builder/factory pattern for default templates. However, the system also supports custom templates, where users can decide which panels should exist in a template.

All nodes follow common interfaces. For example, each node implements:

• from_dict() (load)
• to_dict() (save)
• validate()

and some more like, type, version, name etc.

When “validate” is triggered on a template, it validates all child nodes recursively. Each node then propagates a validation report upward. This report is used to update the UI elements. For example, if an error exists inside a container, the panel header is marked red to visually indicate that the panel contains an error. The same applies to the template in the sortable tree, and so on.

Where the system really shines is in how communication is handled. Upon creation, we pass a CommunicationBroker instance down, so each template gets its own broker. This ensures communication is scoped locally within the template.

class CommunicationBroker:
    """Scoped message broker for validation events. Each template has its own broker instance for isolated event routing."""

    def __init__(self) -> None:
        """Initialize the event broker."""
        self._channels: dict[str, list] = {}

    @classmethod
    def _matches_pattern(cls, channel_name: str, pattern: str) -> bool:
        """Check if a channel name matches a pattern. Supports enhanced wildcard '*' matching for hierarchical channels.

        Examples:
            "panel.123.component.456" matches "panel.*.component.*"
            "panel.123.container.456.component.789" matches "panel.*.container.*.component.*"
            "panel.123.container.456.container.789.component.101" matches "panel.*.container.*"
            "panel.123.container.456.container.789.component.101" matches "panel.123.**"

        Wildcards:
            "*"  - matches exactly one segment
            "**" - matches any number of segments (including zero)

        Returns:
            True if it matches, otherwise False.
        """
        if pattern == channel_name:
            return True

        # Enhanced wildcard matching for hierarchical channels
        if "*" in pattern:
            return cls._match_pattern_parts(channel_name.split("."), pattern.split("."))

        return False

Additionally, the class includes methods to subscribe/unsubscribe, clear communication channels, count subscribers, and support partial matching.

So what happens when a user types into a ui.input()?

@input_text.setter
def input_text(self, value: str) -> None:

    if self._input_text != value:
        old_value = self._input_text
        self._input_text = value
        self._publish_change_event(old_value, value)

def _publish_change_event(self, old_value: str, new_value: str) -> None:
    """Publish validation change event - pure business logic."""
    event = CommunicationEvent(
        event_type=CommunicationTypes.COMPONENT_CHANGED,
        path=self.path,
        variable_name="input_text",
        old_value=old_value,
        new_value=new_value,
        path_names=self.path_names,
    )
    AppLogger.debug(
        f"Input Component published validation event with debug path: {self.debug_path}"
    )

    channel = CommunicationChannel(self.path)
    self.communication_broker.publish(channel, event)

The path is a string composed of "panel.id + container.id + component.id", since each node has a unique internal ID from NiceGUI.

The template subscribes to communication like this:

self._communication_broker.subscribe("panel.*", self._handle_event_communication)  # Panel-level events
self._communication_broker.subscribe("panel.*.container.**", self._handle_event_communication)  # Any nested container hierarchy

def _handle_event_communication(self, event_data: CommunicationEvent) -> None:
    """Template validation changed."""

    if event_data.event_type == CommunicationTypes.SETTINGS_CHANGED:
        if event_data.variable_name == "template_name":
            self.template_name = event_data.new_value
        if event_data.variable_name == "is_exportable":
            self.is_exportable = event_data.new_value

    if event_data.event_type == CommunicationTypes.TEMPLATE_TOC_RENAME:
        self.template_name = event_data.new_value
        return

So how would you create “global” events?

In our case, we don’t need them. However, you could use the same CommunicationBroker system and simply create a global instance.

We do have a few cross-template communication cases, but instead of introducing a global communication channel, those are handled differently.

Each template must have a unique name. There is a unique_name_reference class that maintains a shared list of names. Panels can subscribe a callback to this class. When the method is_unique() is called and the name is not unique, it notifies all registered listeners via their callbacks.

Inside the panel, this triggers a local communication event through its broker, such as "unique_id_changed". This then triggers a revalidation of that specific template, which may update the UI colors depending on whether errors or warnings remain.

I hope this makes sense 🙂

[FabianGoessling]

Hi there, i just stumbled across
an interesting extension

https://github.com/CrystalWindSnake/ex4nicegui

which implements the reactive pattern for nicegui including v-for and so on ( better look at the english Readme). With this added nicegui would behave like reflect and give a more vue native experience. With the latest feats regarding reactive props, is there any roadmap to get rid of the boilerplate ui.refreshable and manual updating all together with eg a v-for implementation? Looking forward to your ideas 🙂

[LeonMusCoden]

I'd love to see more discussion around structuring nicegui apps. Below are my two cents.

I've been using @buiapp 's reaktiv extensively to build various apps. I've not looked at reflex much, but the way I structure my app is (unintentionally) very close to what it recommends.

The benefits are:

• Clear separation of concerns between page lifecycle, business logic, state, and ui components
• Declarative and reactive state. That means changes propagate automatically and only affected computations / ui components are updated. This also makes the data flow explicit and easy to follow for me.
• Component-based app structure: Each major component (like a row of inputs, an output table, ...) receives the state and only reads and writes to it. This means each component is isolated, which makes development and debugging easier.

Below is an example.

I have a page class that initiates the state, the ui components, and communicates with the service layer. I won't include service layer code here as it's essentially just calculation, io, etc.

class FixingsPage:
    """Page to forecast ee spreads."""

    def __init__(self):
        self.state = FixingsState()
        self._setup_ui()
        self._rerun_forecast_effect = Effect(self._calculate_forecast)

        # Register cleanup on disconnect
        ui.context.client.on_disconnect(self.cleanup)

    def _setup_ui(self):
        apply_theme()
        self.inputs = Inputs(self.state, self._calculate)
        self.chart = Chart(self.state)
        self.table = Table(self.state)

        self.notification_container = ui.element()

    async def _calculate(self):
        is_running = self.state.is_running()
        if is_running:
            return
        # ...
        with self.notification_container:
            notification = ui.notification(
                "Running ML model...", type="info", timeout=None, spinner=True
            )
        try:
            result = await run.io_bound(...)
            self.state.result.set(result)
            notification.message = "Done!"
            notification.type = "positive"
        finally:
            notification.timeout = 1
            notification.spinner = False


    def cleanup(self):
        """Cleanup all resources when client disconnects."""
        logger.debug("Cleaning up FixingsPage resources")

        # Dispose reactive effects
        if hasattr(self, "_rerun_forecast_effect"):
            self._rerun_forecast_effect.dispose()

        # Cleanup UI components
        self.chart.cleanup()
        self.table.cleanup()

        # Cleanup state
        self.state.cleanup()


def page():
    """Entrypoint."""
    FixingsPage()

The state holds all the page's data and computes general transformations of the backend data for the frontend.

class FixingsState:
    """State for fixings page."""

    date_filter: Signal[datetime.date]
    spread_type: Signal[SpreadType]
    run_model: Signal[bool]
    run_in_separate_process: Signal[bool]

    result: Signal[FixingsResult | None]
    is_running: Signal[bool]

    latest_market: Computed

    market_forwards: Computed
    saved_forwards: LinkedSignal[pd.DataFrame | None]
    editable_forwards: Computed

    has_result: Computed

    def __init__(self):
        self.date_filter = Signal(datetime.date.today())
        self.spread_type = Signal(SpreadType.Estr3s)
        self.run_model = Signal(True)
        self.run_in_separate_process = Signal(False)

        self.request = Signal(None)
        self.result = Signal(None)
        self.is_running = Signal(False)

        self._live_market_signal = get_market_signal(
            ...
        )
        self.latest_market = Computed(
            self._compute_latest_market
        )

        self.market_forwards = Computed(self._compute_market_forwards)
        self.saved_forwards = LinkedSignal(self._compute_saved_forwards)
        self.editable_forwards = Computed(self._compute_editable_forwards)
        self._save_effect = Effect(self._save_manual_forwards)

        self.has_result = Computed(lambda: self.result() is not None)

# ...

    def cleanup(self):
        """Cleanup reactive effects."""
        logger.debug("Cleaning up FixingsState")
        if hasattr(self, "_save_effect"):
            self._save_effect.dispose()

Finally, every major ui section gets its own class as seen in the page class. Below is the inputs class for example:

class Inputs:
    """Inputs for Fixings page."""

    def __init__(
        self, state: FixingsState, calculate_callback: Callable[[], Awaitable[None]]
    ):
        self.proxy = ReactiveProxy.from_object(state)
        self.calculate_callback = calculate_callback

        self._setup_ui()

    def _setup_ui(self):
        with ui.card().classes("gap-6 rounded-xl shadow-sm border"):
            with ui.card_section().classes("pb-0"):
                ui.label("EE Forecast").classes("text-lg font-semibold")
            with ui.card_section().classes("pt-0"):
                with ui.row().classes("justify-end gap-2 mt-0 items-center"):
                    ui.select(
                        options={
                            spread_type: spread_type.to_string()
                            for spread_type in SpreadType
                        },
                        label="Model Type",
                        value=SpreadType.Estr3s,
                    ).bind_value_to(self.proxy, "spread_type").classes("w-32")

                    with (
                        ui.input(
                            "Start Date",
                            value=datetime.date.today().strftime("%Y-%m-%d"),
                        )
                        .bind_value(
                            self.proxy,
                            "date_filter",
                            forward=lambda val: datetime.datetime.strptime(
                                val, "%Y-%m-%d"
                            ).date()
                            if val and val.strip()
                            else None,
                            backward=lambda dt: dt.strftime("%Y-%m-%d") if dt else "",
                        )
                        .classes("pt-0") as date
                    ):
                        with ui.menu().props("no-parent-event") as menu:
                            with (
                                ui.date()
                                .props('minimal first-day-of-week="1"')
                                .bind_value(date)
                            ) as self.date_select:
                                with ui.row().classes("justify-end"):
                                    ui.button(
                                        "Today", on_click=self._set_date_to_today
                                    ).props("flat")
                                    ui.button("Close", on_click=menu.close).props(
                                        "flat"
                                    )
                        with date.add_slot("append"):
                            ui.icon("edit_calendar").on("click", menu.open).classes(
                                "cursor-pointer"
                            )

                    ui.switch("Run Model").bind_value(self.proxy, "run_model")

                    ui.switch("Separate Process").bind_value(
                        self.proxy, "run_in_separate_process"
                    )

                    ui.button("Calculate", on_click=self.calculate_callback).classes(
                        "ml-4"
                    )

    def _set_date_to_today(self):
        self.date_select.value = datetime.date.today().strftime("%Y-%m-%d")

The ReactiveProxy class is a translation layer between nicegui's BindableProperties and reaktiv. This makes both systems easily compatible and avoids nicegui's default polling behaviour.

[LeonMusCoden]

@buiapp's last point is the important one (in my view):
Adding Computed properties and Effects is the big advantage of a proper managed state.

I also believe a stronger state system should be added to Nicegui. Something like Computed and Effect based on the BindableProperties would go a long way in making application more structured.

One neat feature Nicegui could add is automatic saving / loading of state from browser storage or server side storage.

Looking a bit more at reflex.dev, I don't like how much it forces you to use the classes and utilities provided by the library. The flexibility of something like nicegui+reaktiv ensures nicegui can still support simple script-like code, but also scale up to complex applications.

[FabianGoessling]

Thanks for the diagram, really appreciate it! I get the point of having the computed properties (which is one of my favorite features in a vue.js frontend), and I get that signals and effects are nice if you compare it to working with tandard active links (which run in a loop). But quoting the docs:

There are two types of bindings:

"Bindable properties" automatically detect write access and trigger the value propagation. Most NiceGUI elements use these bindable properties, like value in ui.input or text in ui.label. Basically all properties with bind() methods support this type of binding.
All other bindings are sometimes called "active links". If you bind a label text to some dictionary entry or an attribute of a custom data model, NiceGUI's binding module has to actively check if the value changed. This is done in a refresh_loop() which runs every 0.1 seconds. The interval can be configured via binding_refresh_interval in ui.run().

So what is the difference between using a nicegui bindable dataclass (which uses bindable props) like in my example above (apart leaking using the "frontend" nicegui dependency in the "backend state") to using the reactive version?

I do not want to reject the idea of combining reactive with nicegui, but I share the need for a more structured application with nicegui and have tried several setups without being completely convinced..

EDIT: Checking the calculator example of dataclass vs reaktiv answers part of the question - maybe there is no real difference?

[LeonMusCoden]

Nicegui‘s BindableProperties are in essence reaktiv Signals. My thought (and I believe I speak for the others as well), is to introduce something similar to Computed and Effect to Niceguis existing Event system.

I believe this is necessary for creating more complex, stateful apps. Reflex is very state-driven and has adopted similar features for the reasons mentioned in this thread.

[phifuh]

Thanks for the diagram, really appreciate it! I get the point of having the computed properties (which is one of my favorite features in a vue.js frontend), and I get that signals and effects are nice if you compare it to working with tandard active links (which run in a loop). But quoting the docs:

There are two types of bindings:

"Bindable properties" automatically detect write access and trigger the value propagation. Most NiceGUI elements use these bindable properties, like value in ui.input or text in ui.label. Basically all properties with bind() methods support this type of binding.
All other bindings are sometimes called "active links". If you bind a label text to some dictionary entry or an attribute of a custom data model, NiceGUI's binding module has to actively check if the value changed. This is done in a refresh_loop() which runs every 0.1 seconds. The interval can be configured via binding_refresh_interval in ui.run().

So what is the difference between using a nicegui bindable dataclass (which uses bindable props) like in my example above (apart leaking using the "frontend" nicegui dependency in the "backend state") to using the reactive version?

I do not want to reject the idea of combining reactive with nicegui, but I share the need for a more structured application with nicegui and have tried several setups without being completely convinced..

EDIT: Checking the calculator example of dataclass vs reaktiv answers part of the question - maybe there is no real difference?

I dont know much about reactive but for me its about seperation of concerns and performance. Look at my example:
#4758 (reply in thread)
The difference in a pub/sub pattern is that you dont need to run a refresh_loop on x seconds. The publisher shouts some changes into the void and if someone listens on the right channel he will get notified. The publisher doesnt know about their children, its just doing the shoutout. The only thing I actually havent checked tho is, if the frontend updates run in batch (It should tho, at least I hope it does).

[buiapp]

So the main reason honestly is just separation of concerns like @phifuh seid. I write my business logic first without thinking about the framework at all. Just pure reactive state and computed values. Then later I figure out how to hook it into NiceGUIs UI components (see diagram).

The core logic has then zero dependencies on NiceGUI and makes testing easier.

Also, signals are kinda having a moment right now in the frontend world (Vue 3 has them, SolidJS, Preact, Angular, Svelte) and there's even a TC39 proposal to standardize signals in JavaScript itself. The idea is to have interoperable reactive primitives that work across different frameworks.

I actually emailed with @manzt from AnyWidget about this a while back after finding his own signals package and his idea was, that it would be cool to standardize something like this for Python too as many frameworks already implement a reactivity layer in some form (Posit/Shiny, Solara, Panel, Reflex). The goal could be to standardize the primitives so they can interoperate.