New features and enhancements, breaking changes and migration guide
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.
- **Semantic versioning**
NiceGUI 2.0 starts to implement [semantic versioning](https://semver.org/), which means that we will follow the MAJOR.MINOR.PATCH versioning scheme. This release is a major version because it introduces breaking changes. We will increment the MAJOR version for breaking changes, the MINOR version for new features and enhancements, and the PATCH version for bug fixes.
- **Fix Quasar's layout rules for `ui.card` that remove children's borders and shadows** (726, 1295, 2265, 2301, 3444 by miqsoft, v479038280, ghbm-itk, falkoschindler)
⚠️ **BREAKING:** Quasar's QCard, the foundation of NiceGUI's [`ui.card`](https://nicegui.io/documentation/card), usually comes without any padding and requires nested card sections wrapping the actual content. NiceGUI simplified the use of cards by adding padding, flex layout and gaps automatically. But because a QCard also removes the outer-most borders and shadows of its children, this caused unexpected results in certain cases. NiceGUI 2.0 fixes the behavior of [`ui.card`](https://nicegui.io/documentation/card) by disabling Quasar's respective CSS rules.
- **Improve the API of [`ui.table`](https://nicegui.io/documentation/table)** (#2633, 2731, 3263, 3264, 3525 by bojh, rohitsathish, tmlmt, falkoschindler)
⚠️ **BREAKING:** The API for adding and removing rows in a [`ui.table`](https://nicegui.io/documentation/table) has been improved. Passing rows as multiple arguments has been deprecated. Now these methods expect lists of rows.
The `columns` argument for `ui.table` is optional now. If not provided, the columns are infered from the first row.
A new `update_from_pandas` method has been introduced to update rows and columns from a new dataframe.
A new `column_defaults` parameter has been introduced to allow specifying some properties for all columns at once.
- **Improve support for drawing items in [`ui.leaflet`](https://nicegui.io/documentation/leaflet)** (#2422, 3586 by joseph-fidelis, falkoschindler)
⚠️ **BREAKING:** The [`ui.leaflet`](https://nicegui.io/documentation/leaflet) element used to remove drawn items and required the user code to add new layers to the map for visualization. Now such items remain visible by default. This new behavior can be disabled by passing `hide_drawn_items=True` to `ui.leaflet`.
- **Unify declaration of third-party dependencies** (2991 by falkoschindler, rodja)
⚠️ **BREAKING:** This release deprecates the `libraries`, `extra_libraries` and `exposed_libraries` parameters for subclassing `ui.element`. It introduces a new `dependencies` parameter to be used instead. New examples ["Custom Vue Component"](https://github.com/zauberzeug/nicegui/tree/main/examples/custom_vue_component) and ["Signature Pad"](https://github.com/zauberzeug/nicegui/tree/main/examples/signature_pad) demonstrate how to use NPM and this parameter for integrating custom components based on third-party JavaScript libraries.
- **Reserve bottom space in validation elements for error messages** (2484, 2492, 2738, 3013, 3446, 3660 by akai-1024, huche6, atticus-lv, rodja, falkoschindler)
⚠️ **BREAKING:** UI elements with input validation like [`ui.input`](https://nicegui.io/documentation/input) used to omit the bottom space for a potential error message. This caused a layout jump when the first error occurred. This release fixes this issue be reserving the space by default whenever the `validation` argument and property is not `None`. You can disable this behavior using the "hide-bottom-space" prop.
- **Remove [`ui.timer`](https://nicegui.io/documentation/timer) objects from UI hierarchy after they are finished** (#3626, 3647 by fwerner, rodja)
Especially one-shot timers are now removed from the UI hierarchy after their callback has been executed. This avoids a potential memory leak.
- **Disable FastAPI docs by default** (3570, 3589 by Yuerchu, python-and-fiction, rodja)
⚠️ **BREAKING:** NiceGUI apps used to automatically serve FastAPI docs at /docs, /redoc, and /openapi.json. This behavior has been disabled. You can enable it by passing `fastapi_docs=True` to `ui.run`. Furthermore, you can specify the individual routes by setting `core.app.docs_url`, `core.app.redoc_url`, and `core.app.openapi_url`.
- **Make `client.ip` available before socket connection is established** (2399, 3287, 3445 by rodja, falkoschindler)
⚠️ **BREAKING:** The client's IP is now already available before the page built and is returned to the client. On the auto-index page the `client.ip` property is `None`. If you need to check if the socket connection is established, use `client.has_socket_connection` instead.
- **Remove and update deprecated APIs** (3648 by falkoschindler)
⚠️ **BREAKING:** Several deprecated APIs have been removed. The remaining deprecations will show warnings including the version when they will be removed. Please update your code accordingly.
- `ui.run_javascript()` and related methods:
The `respond` and `check_interval` parameters are not needed anymore and got removed.
- `context`:
The `get_slot_stack()` method has been replaced with the `slot_stack` property.
The `get_slot()` method has been replaced with the `slot` property.
The `get_client()` method has been replaced with the `client` property.
- Layout elements `ui.header`, `ui.footer`, `ui.drawer`, `ui.left_drawer` and `ui.right_drawer`:
Nesting top level layout elements now raises a `RuntimeError`.
- Storage:
NiceGUI no longer migrates files from the system's default encoding to UTF-8. This was only a temporary migration. All storage files should be encoded with UTF-8 by now.
- `ui.aggrid`:
The method `call_api_method` has been replaced with `run_grid_method`.
The method `call_column_method` has been replaced with `run_column_method`.
- `ui.chart` is now `ui.highchart`.
- `ui.open` has been replaced with `ui.navigate.to`.
- `ui.add_style` has been removed. Use `ui.add_css`, `ui.add_scss`, or `ui.add_sass` instead.
Documentation and examples
- Use newer langchain package (3595 by rodja)
Python Dependencies
- Bump ruff from 0.6.2 to 0.6.3 (3646 by dependabot)
- Bump plotly from 5.23.0 to 5.24.0 (3645 by dependabot)
- Bump FastAPI from 0.109.2 to 0.112.2 and remove the upper bound (3384, 3499, 3519, 3604, 3622, 3623 by pierrecdn, dependabot, aersam)
JavaScript Dependencies
The following JavaScript dependencies have been updated to the latest versions (3654 by falkoschindler):
- Vue: 3.3.6 → 3.4.38
- Quasar: 2.13.0 → 2.16.9
- TailwindCSS: 3.2.0 → 3.4.10 (resolves 3169 and 3176)
- Socket.IO: 4.7.2 → 4.7.5
- ES Module Shims: 1.8.0 → 1.10.0
- AG Grid: 30.2.0 → 32.1.0 (resolves 3393 and 3538)
- CodeMirror: 6.0.1 (unchanged)
- ECharts: 5.4.3 → 5.5.1
- ECharts-GL: 2.0.9 (unchanged)
- Leaflet: 1.9.4 (unchanged)
- Leaflet-draw: 1.0.4 (unchanged)
- Mermaid: 10.5.1 → 11.0.2
- nippleJS: 0.10.1 → 0.10.2
- Plotly: 2.27.0 → 2.35.0 (resolves 3086)
- three.js: 0.157.0 → 0.168.0
- tween.js: 21.0.0 → 25.0.0
- vanilla-jsoneditor: 0.18.10 → 0.23.8
Many thanks to all contributors and users who reported issues and provided feedback. We hope you enjoy this new release!