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]

That's the little important detail that many will not see when glancing over the code. 😄

I ported the same shortcut syntax that the Angular framework is using. But alternatively you can also use the .get() method.

For further information about Signals: https://angular.dev/guide/signals

[FabianGoessling]

At first glance i like the approach very much and will look into reactive in more detail.

But from what i understand i can build a similar version with a state class and declare the function as ui.refreshable and trigger the update on state change (eg a little lambda call which calls the state method to update the value AND refresh the ui). I guess this is what @evnchn had in mind.

@buiapp Did you ever look into a combination of reactive state with a pydantic (config-class)?

Overall I still do not like that if i am going the state class route i end up with variables like "is_calculating" cluttering up my backend state. Currently i am using two state classes, a ui_state and a backend_state but this is only a cosmetic change - both states live in the backend and get updated via websockets, which seems unnecessary.

[evnchn]

I guess now is the time that you can include some sample code, and we'll see what is the best way going forward.

[FabianGoessling]

Sorry for the late reply @evnchn , just managed to setup a simple example. First of all a little more of context:

• The application is used in native mode, packaged and essentially running as a local application
• There are no pages, currently tabs are used to get a single page app feeling.
• There are several configurations loaded on startup, those e.g. populate the dropdowns.
• The "core" application is a standalone app and should be usable without the NiceGUI frontend, and this goes for testing as well, there is a full test suite for the "core" app.

# "Core" application
def do_something_fancy(selected_opion):
    print(f"Wow selection option is: {selected_opion}")


class FancyApplication():

    def run_function(self, configuration):
        do_something_fancy(configuration.selected_option)

fancy_app = FancyApplication() # <- this is happening in a bootstrap .py file.

Note that nicegui is not required here. Now the frontend is pretty complicated, meaning I have several components and direct dependence or value binding between components is (at least in my opinion) no good idea. Therefore I would introduce a state class:

class State():
    dialog_is_open = False
    selected_option = "A"
    available_options = ["A", "B", "C"]  # loaded from a config or env file

state = State() # <- this is happening in a bootstrap .py file.

and while at first glance this seems okay, it gets pretty messy if the state has >30 props. Also it mixes frontend and backend variables: 'dialog_is_open' is not required and not wanted in the 'run_function' above, even worse in testing I have to take care of the attribute. To roundup the ui would be:

from nicegui import  ui

with ui.dialog().bind_value(state, "dialog_is_open"):
    ui.label("hihi")

ui.select(options=state.available_options).bind_value(state, "selected_option")

## in another tab, different component

ui.label(text="dialog is open").bind_visibility(state, "dialog_is_open")

ui.button("run app").on_click(lambda x: fancy_app.run_function(state))
ui.switch("show dialog").bind_value(state, "dialog_is_open")
ui.run()

Now, considering the "mixed" state, I separate the state class in two states, a "frontend-state", which only holds variables related to the ui and a "backend_state" which holds variables for the "core" app. Then I added a "Component" which allows to pass through the states:

class Component():

    def __init__(self, backend_state, frontend_state):
        self.backend_state = backend_state
        self.fronted_state = frontend_state
    
    def ui(self):
        # to be implemented
        pass


class DialogAndSelectComponent(Component):
    def ui(self):
        with ui.dialog().bind_value(self.fronted_state, "dialog_is_open"):
            ui.label("hihi")

        ui.select(options=self.fronted_state.available_options).bind_value(self.backend_state, "selected_option")

class AnotherGroupOfElements(Component):
    def ui(self):
        ui.label(text="dialog is open").bind_visibility(self.fronted_state, "dialog_is_open")

        ui.button("run app").on_click(lambda x: fancy_app.run_function(self.backend_state))
        ui.switch("show dialog").bind_value(self.fronted_state, "dialog_is_open")

Then the frontend is created by:

# Frontend
DialogAndSelectComponent().ui()
AnotherGroupOfElements().ui()

ui.run()

While I think the above approach helps, I wonder how others manage their state, thus my initial post. Moreover from what I understand, even though I separate the states, the dialog_is_open prop "lives" on the python side and a change results in two websocket updates, a "ping-pong play" which is unnecessary (and this would happen with your @buiapp package as well, right?) - in a pure .vue component such states "stay" inside the client browser. I am very interested in your views and ideas regarding the above, so let me know what you think and how you would solve it.

[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.)