NiceGUI: Web-based user interfaces with Python. The nice way.

This major release introduces several new features and enhancements, as well as breaking changes. We always try to keep breaking changes to a minimum, guide you through the migration process using deprecation warnings, and provide migration instructions. Please read the following release notes carefully to understand the changes and adapt your code accordingly before upgrading.

New features and enhancements

• Introduce NiceGUI script mode to replace the awkward auto-index page (#5005 by @rodja, @falkoschindler)
• Introduce root page parameter for ui.run to simplify single-page applications (#4964, #5005 by @rodja, @falkoschindler)
• Introduce an Event system to communicate between UI and long-living objects (#5107 by @falkoschindler, @denniswittich)
• Simplify pytests by loading a main file with runpy (#5102 by @rodja, @falkoschindler)
• Make props, classes and style observable to send updates automatically (#4978 by @lawrenceakka, @falkoschindler, @rodja)
• Upgrade to Tailwind 4 (#5057 by @falkoschindler)
• Drop support for Python 3.8 (#4329 by @Solipsistmonkey, @falkoschindler)
• Introduce ValueChangeEventArguments.previous_value (#4410, #4456 by @me21, @falkoschindler, @evnchn)
• Introduce a strict option for binding methods (#5040 by @denniswittich, @codingpaula, @falkoschindler)
• Introduce a sanitize argument for ui.html and ui.chat_message (#5187 by @oxqnd, @falkoschindler, @rodja, @evnchn)
• Improve support for languages with right-to-left text direction (#5045, #5058 by @M6stafa, @falkoschindler)
• Use q-scroll_area for ui.log to preserve a fixed height (#4925, #4935 by @e-nesse, @falkoschindler)
• Let ui.clipboard.read() return None if the clipboard API isn't available (#4236, #4237 by @weinibuliu, @falkoschindler, @evnchn)
• Call lifecycle event handlers more consistently (#5173 by @falkoschindler, @evnchn, @rodja)
• Improve UploadEventArguments and MultiUploadEventArguments to avoid unclosed resources (#5178 by @rodja, @evnchn, @falkoschindler)
• Re-initialize the process pool if it was broken by a bad run.cpu_bound (#4980, #5129 by @jammerhund, @evnchn, @rodja, @falkoschindler)
• Remove deprecated code and APIs (#5037 by @falkoschindler)
• Treat pytest warnings as errors (#5182, #5186 by @evnchn, @rodja, @falkoschindler)

⚠️ Breaking changes and migration guide

1. Shared auto-index pages (not using @ui.page)

   UI elements defined in global scope have been added to a static shared "auto-index client" served at "/". This caused a multitude of problems throughout the code base, so we decided to remove this shared client.

   In version 3.0 you have the following options:

   • Keep putting (all) UI elements in global scope. We call such apps without page functions "NiceGUI scripts". They will automatically re-evaluated inside an implicit page function when visiting "/". This is almost a drop-in replacement for the auto-index client, but:

     • NiceGUI scripts can't contain page functions.
     • The UI isn't shared but re-created on every page visit.

   • Wrap all UI in a singe function and pass it to the new positional root parameter in ui.run. This is especially handy in combination with ui.sub_pages. This way you can create rich single-page applications without worrying about defining the correct routes with @page decorators.

   • Use page functions for all your pages, including the index page at "/".

   Note that we are introducing a new Event class. Together with the binding module this helps to synchronize long-living objects with short-living UI without relying on a long-living shared client.

2. Calling .props(), .classes() or .style() with subsequent .update()

   A subsequent .update() is not necessary anymore because props, classes and style are now observable collections that trigger updates automatically.

   When overwriting the update method in custom elements, infinite recursions can occur. If, e.g., the update methods uses .prop() before calling super().update(), the .prop() call will cause an infinite cycle. Wrap it with with self._props.suspend_updates(): (and similar for classes and style) to pause automatic updates in such cases.

3. Modifying ui.table and ui.aggrid content

   Before NiceGUI 3.0 it was possible create tables or AG Grids like ui.table(columns=columns, rows=rows, ...) or ui.aggrid({'columnDefs': columns, 'rowData': rows, ...) and update it later by modifying the original columns or rows. This is not possible anymore.

   In NiceGUI 3.0 you need to modify table.rows, table.columns or aggrid.options instead. A subsequent table.update() or aggrid.update is not necessary anymore.

4. Upgrade to Tailwind 4; dropping the ui.element.tailwind API

   Although very similar, Tailwind 4 comes with some breaking changes. Check your layout carefully after upgrading. We noticed differences especially with line spacing and borders.

   For technical reasons updating and maintaining our ui.element.tailwind API became unfeasible. So we decided to remove it. For auto-completing Tailwind classes, we recommend the NiceGUI extension for Visual Studio Code by @DaelonSuzuka.

5. Dropping support for Python 3.8

   Almost one year after Python 3.8 reached its end-of-life, it was time to drop support. This allowed us to update the code to a newer standard and resolve some issues with Python dependencies that already dropped 3.8 a while ago.

6. ValueChangeEventArguments got a new previous_value attribute

   In some situations it might be helpful to have access to both, the current and the previous value. Therefore we added previous_value to the ValueChangeEventArguments.

   Custom elements that emit ValueChangeEventArguments need to provide the previous value.

7. Binding from and to non-existing object properties

   Binding used to fail silently if one of the attributes doesn't exist. In case of dictionaries this was intended, because they are often used to bind to persistent storage which is empty by default. But for object properties this can lead to very subtle bugs, e.g. after renaming properties and not updating the attribue names in binding functions.

   In 3.0 object properties will be checked for existence by default. Missing dictionaries will continue to be ignored.

   You can fine-tune this behavior using the strict: bool | None = None parameter (None: check object properties and ignore dictionaries).

8. Sanitize content for ui.html and ui.chat_message

   To prevent NiceGUI apps from accidentally displaying unsafe user input as HTML, ui.html and ui.chat_message now have a sanitize argument. It can be set to a function like Sanitizer().sanitize from the html-sanitizer module, or False to disable sanitization. While ui.html requires the new argument to be specified, ui.chat_message only requires it if text_html=True.

   Note that the html-sanitizer module is not included in NiceGUI and needs to be installed separately is needed.

9. ui.log with unspecified width can collapse inside containers with unspecified width

   We noticed that the height of ui.log could be affected by its content, which is unexpected. Therefore we decided to use a scroll area for a more robust layout.

   Now the width of ui.log can collapse when placed inside a container with an unspecified width. Either give the container some width or specify the width of ui.log.

10. ui.clipboard.read() returns None if the clipboard API isn't available

    The read() function used to return an empty string if the clipboard API is not available. This was indistinguishable from an empty clipboard.

    Now the read() function returns None if the clipboard API is not available.

11. Lifecycle events are called more consistently

    Handlers registered with on_disconnect used to be called only after the client fails to reconnect and is deleted.

    Now disconnect handlers are immediatelly called when a connection is lost, even if the client reconnects after a short while.

    A new on_delete function can be used to register callbacks for the deletion of a client.

12. UploadEventArguments and MultiUploadEventArguments have changed

    Instead of content: BinaryIO, name: str and type: str the event arguments now contain a single field file: FileUpload, which contains

    • properties name: str and content_type: str as well as
    • methods read, text, json, iterate, save and size to access the content.

13. Remove deprecated code and APIs

    • app.add_static_file and app.add_media_file raises FileNotFoundError instead of ValueError in case of non-existing files. Since FileNotFoundError is NOT a subclass of ValueError, existing code which except ValueError will fail to catch the new FileNotFoundError.
    • ui.aggrid: run_column_method is gone. Use run_grid_method instead.
    • ui.table calling add_rows()/remove_rows() with variable-length arguments no longer works. Pass a list instead or use add_row()/remove_row() for a single row.
    • ui.open is gone. Use ui.navigate.to.
    • nicegui.testing.conftest is gone and you can no longer import it. Use pytest_plugins = ["nicegui.testing.plugin"] instead.
    • element.on parameter js_handler now has type str instead of str | None. You can pass a None and it still works, but your type checker won't be happy, and we can't promise it will work for much longer afterwards.

JavaScript Dependencies

The infrastructure for managing node packages has been improved significantly (#4163, #5021 by @simontaurus, @evnchn, @falkoschindler). The following JavaScript dependencies have been updated to the latest versions (#5034, #5168, #5190 by @falkoschindler):

• @tailwindcss/browser: 3.4.10 → 4.1.13 (#5057 by @falkoschindler)
• es-module-shims: 1.10.0 → 2.6.2
• quasar: 2.16.9 → 2.18.5 (resolves #4892 by @eddie3ruff, @evnchn, @xaptronic, @falkoschindler)
• socket.io: 4.7.5 → 4.8.1
• vue: 3.4.28 → 3.5.22
• ag-grid-community: 32.1.0 → 34.2.0 (resolves #3854 by @python-and-novella, @mockey, @falkoschindler)
• codemirror: 6.0.1 → 6.0.2
• @codemirror/language-data: 6.5.1 (new)
• @codemirror/theme-one-dark: 6.1.3 (new)
• @uiw/codemirror-themes-all: 4.25.2 (new)
• @babel/runtime: 7.28.4 (new)
• echarts: 5.5.1 → 6.0.0
• echarts-gl: 2.0.9 (unchanged)
• nipplejs: 0.10.2 (unchanged)
• vanilla-jsoneditor: 0.23.8 → 3.10.0
• leaflet: 1.9.4 (unchanged)
• leaflet-draw: 1.0.4 (unchanged)
• mermaid: 11.0.2 → 11.12.0
• plotly.js: 2.35.0 → 3.1.1
• three: 0.168.0 → 0.180.1
• @tweenjs/tween.js: 25.0.0 (unchanged)

The following contributions helped to fix problems during integration:

• Support AG Grid v34 Theme API for ui.aggrid (#5122, #5131 by @egursu, @evnchn, @falkoschindler)
• Segregate Quasar's important rules in Python-side (#5156, #5171 by @python-and-novella, @evnchn, @falkoschindler)
• Support client connection when Chrome performs speculative loading (#5115, #5116 by @python-and-novella, @rodja, @evnchn, @falkoschindler)

Special thanks to all our sponsors and contributors! ✨

🙏 Want to support this project? Check out our GitHub Sponsors page to help us keep building amazing features!