ui.aggrid

AG Grid

An element to create a grid using AG Grid.

The methods run_grid_method and run_row_method can be used to interact with the AG Grid instance on the client.

auto_size_columns:
options:	dictionary of AG Grid options
html_columns:	list of columns that should be rendered as HTML (default: [])
theme:	AG Grid theme (default: 'balham')
	whether to automatically resize columns to fit the grid width (default: True)

main.py

from nicegui import ui

grid = ui.aggrid({
    'defaultColDef': {'flex': 1},
    'columnDefs': [
        {'headerName': 'Name', 'field': 'name'},
        {'headerName': 'Age', 'field': 'age'},
        {'headerName': 'Parent', 'field': 'parent', 'hide': True},
    ],
    'rowData': [
        {'name': 'Alice', 'age': 18, 'parent': 'David'},
        {'name': 'Bob', 'age': 21, 'parent': 'Eve'},
        {'name': 'Carol', 'age': 42, 'parent': 'Frank'},
    ],
    'rowSelection': 'multiple',
}).classes('max-h-40')

def update():
    grid.options['rowData'][0]['age'] += 1
    grid.update()

ui.button('Update', on_click=update)
ui.button('Select all', on_click=lambda: grid.run_grid_method('selectAll'))
ui.button('Show parent', on_click=lambda: grid.run_grid_method('setColumnsVisible', ['parent'], True))

ui.run()

NiceGUI

Select AG Grid Rows

You can add checkboxes to grid cells to allow the user to select single or multiple rows.

To retrieve the currently selected rows, use the get_selected_rows method. This method returns a list of rows as dictionaries.

If rowSelection is set to 'single' or to get the first selected row, you can also use the get_selected_row method. This method returns a single row as a dictionary or None if no row is selected.

See the AG Grid documentation for more information.

main.py

from nicegui import ui

grid = ui.aggrid({
    'columnDefs': [
        {'headerName': 'Name', 'field': 'name', 'checkboxSelection': True},
        {'headerName': 'Age', 'field': 'age'},
    ],
    'rowData': [
        {'name': 'Alice', 'age': 18},
        {'name': 'Bob', 'age': 21},
        {'name': 'Carol', 'age': 42},
    ],
    'rowSelection': 'multiple',
}).classes('max-h-40')

async def output_selected_rows():
    rows = await grid.get_selected_rows()
    if rows:
        for row in rows:
            ui.notify(f"{row['name']}, {row['age']}")
    else:
        ui.notify('No rows selected.')

async def output_selected_row():
    row = await grid.get_selected_row()
    if row:
        ui.notify(f"{row['name']}, {row['age']}")
    else:
        ui.notify('No row selected!')

ui.button('Output selected rows', on_click=output_selected_rows)
ui.button('Output selected row', on_click=output_selected_row)

ui.run()

NiceGUI

Filter Rows using Mini Filters

You can add mini filters to the header of each column to filter the rows.

Note how the "agTextColumnFilter" matches individual characters, like "a" in "Alice" and "Carol", while the "agNumberColumnFilter" matches the entire number, like "18" and "21", but not "1".

main.py

from nicegui import ui

ui.aggrid({
    'columnDefs': [
        {'headerName': 'Name', 'field': 'name', 'filter': 'agTextColumnFilter', 'floatingFilter': True},
        {'headerName': 'Age', 'field': 'age', 'filter': 'agNumberColumnFilter', 'floatingFilter': True},
    ],
    'rowData': [
        {'name': 'Alice', 'age': 18},
        {'name': 'Bob', 'age': 21},
        {'name': 'Carol', 'age': 42},
    ],
}).classes('max-h-40')

ui.run()

NiceGUI

AG Grid with Conditional Cell Formatting

This demo shows how to use cellClassRules to conditionally format cells based on their values.

main.py

from nicegui import ui

ui.aggrid({
    'columnDefs': [
        {'headerName': 'Name', 'field': 'name'},
        {'headerName': 'Age', 'field': 'age', 'cellClassRules': {
            'bg-red-300': 'x < 21',
            'bg-green-300': 'x >= 21',
        }},
    ],
    'rowData': [
        {'name': 'Alice', 'age': 18},
        {'name': 'Bob', 'age': 21},
        {'name': 'Carol', 'age': 42},
    ],
})

ui.run()

NiceGUI

Create Grid from Pandas DataFrame

You can create an AG Grid from a Pandas DataFrame using the from_pandas method. This method takes a Pandas DataFrame as input and returns an AG Grid.

main.py

import pandas as pd
from nicegui import ui

df = pd.DataFrame(data={'col1': [1, 2], 'col2': [3, 4]})
ui.aggrid.from_pandas(df).classes('max-h-40')

ui.run()

NiceGUI

Create Grid from Polars DataFrame

You can create an AG Grid from a Polars DataFrame using the from_polars method. This method takes a Polars DataFrame as input and returns an AG Grid.

Added in version 2.7.0

main.py

import polars as pl
from nicegui import ui

df = pl.DataFrame(data={'col1': [1, 2], 'col2': [3, 4]})
ui.aggrid.from_polars(df).classes('max-h-40')

ui.run()

NiceGUI

Render columns as HTML

You can render columns as HTML by passing a list of column indices to the html_columns argument.

main.py

from nicegui import ui

ui.aggrid({
    'columnDefs': [
        {'headerName': 'Name', 'field': 'name'},
        {'headerName': 'URL', 'field': 'url'},
    ],
    'rowData': [
        {'name': 'Google', 'url': '<a href="https://google.com">https://google.com</a>'},
        {'name': 'Facebook', 'url': '<a href="https://facebook.com">https://facebook.com</a>'},
    ],
}, html_columns=[1])

ui.run()

NiceGUI

Respond to an AG Grid event

All AG Grid events are passed through to NiceGUI via the AG Grid global listener. These events can be subscribed to using the .on() method.

main.py

from nicegui import ui

ui.aggrid({
    'columnDefs': [
        {'headerName': 'Name', 'field': 'name'},
        {'headerName': 'Age', 'field': 'age'},
    ],
    'rowData': [
        {'name': 'Alice', 'age': 18},
        {'name': 'Bob', 'age': 21},
        {'name': 'Carol', 'age': 42},
    ],
}).on('cellClicked', lambda event: ui.notify(f'Cell value: {event.args["value"]}'))

ui.run()

NiceGUI

AG Grid with complex objects

You can use nested complex objects in AG Grid by separating the field names with a period. (This is the reason why keys in rowData are not allowed to contain periods.)

main.py

from nicegui import ui

ui.aggrid({
    'columnDefs': [
        {'headerName': 'First name', 'field': 'name.first'},
        {'headerName': 'Last name', 'field': 'name.last'},
        {'headerName': 'Age', 'field': 'age'}
    ],
    'rowData': [
        {'name': {'first': 'Alice', 'last': 'Adams'}, 'age': 18},
        {'name': {'first': 'Bob', 'last': 'Brown'}, 'age': 21},
        {'name': {'first': 'Carol', 'last': 'Clark'}, 'age': 42},
    ],
}).classes('max-h-40')

ui.run()

NiceGUI

AG Grid with dynamic row height

You can set the height of individual rows by passing a function to the getRowHeight argument.

main.py

from nicegui import ui

ui.aggrid({
    'columnDefs': [{'field': 'name'}, {'field': 'age'}],
    'rowData': [
        {'name': 'Alice', 'age': '18'},
        {'name': 'Bob', 'age': '21'},
        {'name': 'Carol', 'age': '42'},
    ],
    ':getRowHeight': 'params => params.data.age > 35 ? 50 : 25',
}).classes('max-h-40')

ui.run()

NiceGUI

Run row methods

You can run methods on individual rows by using the run_row_method method. This method takes the row ID, the method name and the method arguments as arguments. The row ID is either the row index (as a string) or the value of the getRowId function.

The following demo shows how to use it to update cell values. Note that the row selection is preserved when the value is updated. This would not be the case if the grid was updated using the update method.

main.py

from nicegui import ui

grid = ui.aggrid({
    'columnDefs': [
        {'field': 'name', 'checkboxSelection': True},
        {'field': 'age'},
    ],
    'rowData': [
        {'name': 'Alice', 'age': 18},
        {'name': 'Bob', 'age': 21},
        {'name': 'Carol', 'age': 42},
    ],
    ':getRowId': '(params) => params.data.name',
})
ui.button('Update',
          on_click=lambda: grid.run_row_method('Alice', 'setDataValue', 'age', 99))

ui.run()

NiceGUI

Filter return values

You can filter the return values of method calls by passing string that defines a JavaScript function. This demo runs the grid method "getDisplayedRowAtIndex" and returns the "data" property of the result.

Note that requesting data from the client is only supported for page functions, not for the shared auto-index page.

main.py

from nicegui import ui

@ui.page('/')
def page():
    grid = ui.aggrid({
        'columnDefs': [{'field': 'name'}],
        'rowData': [{'name': 'Alice'}, {'name': 'Bob'}],
    })

    async def get_first_name() -> None:
        row = await grid.run_grid_method('g => g.getDisplayedRowAtIndex(0).data')
        ui.notify(row['name'])

    ui.button('Get First Name', on_click=get_first_name)

ui.run()

NiceGUI

Handle theme change

You can change the theme of the AG Grid by adding or removing classes. This demo shows how to change the theme using a switch.

main.py

from nicegui import events, ui

grid = ui.aggrid({})

def handle_theme_change(e: events.ValueChangeEventArguments):
    grid.classes(add='ag-theme-balham-dark' if e.value else 'ag-theme-balham',
                 remove='ag-theme-balham ag-theme-balham-dark')

ui.switch('Dark', on_change=handle_theme_change)

ui.run()

NiceGUI

Reference

Initializer

options:dictionary of AG Grid options
html_columns:list of columns that should be rendered as HTML (default: [])
theme:AG Grid theme (default: 'balham')
auto_size_columns:
 whether to automatically resize columns to fit the grid width (default: True)

Properties

classes: 'Classes[Self]'

The classes of the element.

is_deleted: 'bool'

Whether the element has been deleted.

is_ignoring_events: 'bool'

Return whether the element is currently ignoring events.

options: Dict

The options dictionary.

props: 'Props[Self]'

The props of the element.

style: 'Style[Self]'

The style of the element.

visible: BindableProperty

Methods

add_resource(path: Union[str, Path]) -> None

Add a resource to the element.

param path:	path to the resource (e.g. folder with CSS and JavaScript files)

add_slot(name: str, template: Optional[str] = None) -> Slot

Add a slot to the element.

NiceGUI is using the slot concept from Vue: Elements can have multiple slots, each possibly with a number of children. Most elements only have one slot, e.g. a ui.card (QCard) only has a default slot. But more complex elements like ui.table (QTable) can have more slots like "header", "body" and so on. If you nest NiceGUI elements via with ui.row(): ... you place new elements inside of the row's default slot. But if you use with table.add_slot(...): ..., you enter a different slot.

The slot stack helps NiceGUI to keep track of which slot is currently used for new elements. The parent field holds a reference to its element. Whenever an element is entered via a with expression, its default slot is automatically entered as well.

param name:	name of the slot
param template:	Vue template of the slot
return:	the slot

ancestors(include_self: bool = False) -> Iterator[Element]

Iterate over the ancestors of the element.

param include_self:
	whether to include the element itself in the iteration

bind_visibility(target_object: Any, target_name: str = 'visible', forward: Callable[..., Any] = [...], backward: Callable[..., Any] = [...], value: Any = None) -> Self

Bind the visibility of this element to the target object's target_name property.

The binding works both ways, from this element to the target and from the target to this element. The update happens immediately and whenever a value changes. The backward binding takes precedence for the initial synchronization.

param target_object:
	The object to bind to.
param target_name:
	The name of the property to bind to.
param forward:	A function to apply to the value before applying it to the target.
param backward:	A function to apply to the value before applying it to this element.
param value:	If specified, the element will be visible only when the target value is equal to this value.

bind_visibility_from(target_object: Any, target_name: str = 'visible', backward: Callable[..., Any] = [...], value: Any = None) -> Self

Bind the visibility of this element from the target object's target_name property.

The binding works one way only, from the target to this element. The update happens immediately and whenever a value changes.

param target_object:
	The object to bind from.
param target_name:
	The name of the property to bind from.
param backward:	A function to apply to the value before applying it to this element.
param value:	If specified, the element will be visible only when the target value is equal to this value.

bind_visibility_to(target_object: Any, target_name: str = 'visible', forward: Callable[..., Any] = [...]) -> Self

Bind the visibility of this element to the target object's target_name property.

The binding works one way only, from this element to the target. The update happens immediately and whenever a value changes.

param target_object:
	The object to bind to.
param target_name:
	The name of the property to bind to.
param forward:	A function to apply to the value before applying it to the target.

clear() -> None

Remove all child elements.

default_classes(add: Optional[str] = None, remove: Optional[str] = None, toggle: Optional[str] = None, replace: Optional[str] = None) -> type[Self]

Apply, remove, toggle, or replace default HTML classes.

This allows modifying the look of the element or its layout using Tailwind or Quasar classes.

Removing or replacing classes can be helpful if predefined classes are not desired. All elements of this class will share these HTML classes. These must be defined before element instantiation.

param add:	whitespace-delimited string of classes
param remove:	whitespace-delimited string of classes to remove from the element
param toggle:	whitespace-delimited string of classes to toggle (added in version 2.7.0)
param replace:	whitespace-delimited string of classes to use instead of existing ones

default_props(add: Optional[str] = None, remove: Optional[str] = None) -> type[Self]

Add or remove default props.

This allows modifying the look of the element or its layout using Quasar props. Since props are simply applied as HTML attributes, they can be used with any HTML element. All elements of this class will share these props. These must be defined before element instantiation.

Boolean properties are assumed True if no value is specified.

param add:	whitespace-delimited list of either boolean values or key=value pair to add
param remove:	whitespace-delimited list of property keys to remove

default_style(add: Optional[str] = None, remove: Optional[str] = None, replace: Optional[str] = None) -> type[Self]

Apply, remove, or replace default CSS definitions.

Removing or replacing styles can be helpful if the predefined style is not desired. All elements of this class will share these CSS definitions. These must be defined before element instantiation.

param add:	semicolon-separated list of styles to add to the element
param remove:	semicolon-separated list of styles to remove from the element
param replace:	semicolon-separated list of styles to use instead of existing ones

delete() -> None

Delete the element and all its children.

descendants(include_self: bool = False) -> Iterator[Element]

Iterate over the descendants of the element.

param include_self:
	whether to include the element itself in the iteration

@classmethod
from_pandas(df: pd.DataFrame, theme: str = 'balham', auto_size_columns: bool = True, options: Dict = {}) -> Self

Create an AG Grid from a Pandas DataFrame.

Note: If the DataFrame contains non-serializable columns of type datetime64[ns], timedelta64[ns], complex128 or period[M], they will be converted to strings. To use a different conversion, convert the DataFrame manually before passing it to this method. See issue 1698 for more information.

param auto_size_columns:
param df:	Pandas DataFrame
param theme:	AG Grid theme (default: 'balham')
	whether to automatically resize columns to fit the grid width (default: True)
param options:	dictionary of additional AG Grid options
return:	AG Grid element

@classmethod
from_polars(df: pl.DataFrame, theme: str = 'balham', auto_size_columns: bool = True, options: Dict = {}) -> Self

Create an AG Grid from a Polars DataFrame.

If the DataFrame contains non-UTF-8 datatypes, they will be converted to strings. To use a different conversion, convert the DataFrame manually before passing it to this method.

Added in version 2.7.0

param auto_size_columns:
param df:	Polars DataFrame
param theme:	AG Grid theme (default: 'balham')
	whether to automatically resize columns to fit the grid width (default: True)
param options:	dictionary of additional AG Grid options
return:	AG Grid element

get_client_data(timeout: float = 1, method: Literal['all_unsorted', 'filtered_unsorted', 'filtered_sorted', 'leaf'] = 'all_unsorted') -> List[Dict]

Get the data from the client including any edits made by the client.

This method is especially useful when the grid is configured with 'editable': True.

See AG Grid API for more information.

Note that when editing a cell, the row data is not updated until the cell exits the edit mode. This does not happen when the cell loses focus, unless stopEditingWhenCellsLoseFocus: True is set.

param timeout:	timeout in seconds (default: 1 second)
param method:	method to access the data, "all_unsorted" (default), "filtered_unsorted", "filtered_sorted", "leaf"
return:	list of row data

get_computed_prop(prop_name: str, timeout: float = 1) -> AwaitableResponse

Return a computed property.

This function should be awaited so that the computed property is properly returned.

param prop_name:
	name of the computed prop
param timeout:	maximum time to wait for a response (default: 1 second)

get_selected_row() -> Optional[Dict]

Get the single currently selected row.

This method is especially useful when the grid is configured with rowSelection: 'single'.

return:	row data of the first selection if any row is selected, otherwise None

get_selected_rows() -> List[Dict]

Get the currently selected rows.

This method is especially useful when the grid is configured with rowSelection: 'multiple'.

See AG Grid API for more information.

return:	list of selected row data

load_client_data() -> None

Obtain client data and update the element's row data with it.

This syncs edits made by the client in editable cells to the server.

Note that when editing a cell, the row data is not updated until the cell exits the edit mode. This does not happen when the cell loses focus, unless stopEditingWhenCellsLoseFocus: True is set.

mark(*markers: str) -> Self

Replace markers of the element.

Markers are used to identify elements for querying with ElementFilter which is heavily used in testing but can also be used to reduce the number of global variables or passing around dependencies.

param markers:	list of strings or single string with whitespace-delimited markers; replaces existing markers

move(target_container: Optional[Element] = None, target_index: int = -1, target_slot: Optional[str] = None) -> None

Move the element to another container.

param target_container:
	container to move the element to (default: the parent container)
param target_index:
	index within the target slot (default: append to the end)
param target_slot:
	slot within the target container (default: default slot)

on(type: str, handler: Optional[events.Handler[events.GenericEventArguments]] = None, args: Union[None, Sequence[str], Sequence[Optional[Sequence[str]]]] = None, throttle: float = 0.0, leading_events: bool = True, trailing_events: bool = True, js_handler: Optional[str] = None) -> Self

Subscribe to an event.

param leading_events:
param type:	name of the event (e.g. "click", "mousedown", or "update:model-value")
param handler:	callback that is called upon occurrence of the event
param args:	arguments included in the event message sent to the event handler (default: None meaning all)
param throttle:	minimum time (in seconds) between event occurrences (default: 0.0)
	whether to trigger the event handler immediately upon the first event occurrence (default: True)
param trailing_events:
	whether to trigger the event handler after the last event occurrence (default: True)
param js_handler:
	JavaScript code that is executed upon occurrence of the event, e.g. (evt) => alert(evt) (default: None)

remove(element: Union[Element, int]) -> None

Remove a child element.

param element:	either the element instance or its ID

run_column_method(name: str, *args, timeout: float = 1) -> nicegui.awaitable_response.AwaitableResponse

This method is deprecated. Use run_grid_method instead.

See https://www.ag-grid.com/javascript-data-grid/column-api/ for more information

run_grid_method(name: str, *args, timeout: float = 1) -> nicegui.awaitable_response.AwaitableResponse

Run an AG Grid API method.

See AG Grid API for a list of methods.

If the function is awaited, the result of the method call is returned. Otherwise, the method is executed without waiting for a response.

param name:	name of the method
param args:	arguments to pass to the method
param timeout:	timeout in seconds (default: 1 second)
return:	AwaitableResponse that can be awaited to get the result of the method call

run_method(name: str, *args: Any, timeout: float = 1) -> AwaitableResponse

Run a method on the client side.

If the function is awaited, the result of the method call is returned. Otherwise, the method is executed without waiting for a response.

param name:	name of the method
param args:	arguments to pass to the method
param timeout:	maximum time to wait for a response (default: 1 second)

run_row_method(row_id: str, name: str, *args, timeout: float = 1) -> nicegui.awaitable_response.AwaitableResponse

Run an AG Grid API method on a specific row.

See AG Grid Row Reference for a list of methods.

If the function is awaited, the result of the method call is returned. Otherwise, the method is executed without waiting for a response.

param row_id:	id of the row (as defined by the `getRowId` option)
param name:	name of the method
param args:	arguments to pass to the method
param timeout:	timeout in seconds (default: 1 second)
return:	AwaitableResponse that can be awaited to get the result of the method call

set_visibility(visible: bool) -> None

Set the visibility of this element.

param visible:	Whether the element should be visible.

tooltip(text: str) -> Self

Add a tooltip to the element.

param text:	text of the tooltip

update() -> None

Update the element on the client side.

Inheritance

Element
Visibility