AgGrid

AgGrid is the main function used to render the grid.

st_aggrid.AgGrid(data: DataFrame | str, gridOptions: Dict | None = None, height: int | None = None, width: int | None = None, fit_columns_on_grid_load: bool = False, columns_auto_size_mode: ColumnsAutoSizeMode = ColumnsAutoSizeMode.NO_AUTOSIZE, update_mode: GridUpdateMode = GridUpdateMode.MODEL_CHANGED, data_return_mode: DataReturnMode = DataReturnMode.AS_INPUT, allow_unsafe_jscode: bool = False, enable_enterprise_modules: bool = True, license_key: str | None = None, try_to_convert_back_to_original_types: bool = True, conversion_errors: str = 'coerce', reload_data: bool = False, columns_state: List | None = None, filter_state: Dict | None = None, theme: str = AgGridTheme.STREAMLIT, custom_css: Dict | None = None, use_legacy_selected_rows: bool = False, key: Any | None = None, update_on: List = [], enable_quicksearch: bool = False, excel_export_mode: ExcelExportMode = ExcelExportMode.NONE, excel_export_multiple_sheet_params: Mapping | None = None, **default_column_parameters) → AgGridReturn

Renders a DataFrame using AgGrid.

Parameters:

• data (pd.DataFrame) – The underlaying dataframe to be used.

• gridOptions (Dict, optional) – A dictionary of options for ag-grid. Documentation on www.ag-grid.com. If None, default grid options will be created with GridOptionsBuilder.from_dataframe() call. Defaults to None

• height (int, optional) – The grid height in pixels. If None, grid will enable Auto Height by default https://www.ag-grid.com/react-data-grid/grid-size/#dom-layout. Defaults to None

• width (int, optional) – Deprecated. The grid width. Defaults to None

• fit_columns_on_grid_load (bool, optional) – Deprecated, use columns_auto_size_mode. Will adjust columns to fit grid width on grid load. Defaults to False

• columns_auto_size_mode (st_aggrid.shared.ColumnsAutoSizeMode, optional) –

  Sets columns auto size behavior on grid load event. More info: https://www.ag-grid.com/react-data-grid/column-sizing/#auto-size-columns

  • ColumnsAutoSizeMode.NO_AUTOSIZE -> No column resizing. Width defined at gridOptins is used.

  • ColumnsAutoSizeMode.FIT_ALL_COLUMNS_TO_VIEW -> Make the currently visible columns fit the screen. The columns will scale (growing or shrinking) to fit the available width.

  • ColumnsAutoSizeMode.FIT_CONTENTS -> Grid will work out the best width to fit the contents of the cells in the column.

  Defaults to ColumnsAutoSizeMode.NO_AUTOSIZE

• update_mode (st_aggrid.shared.GridUpdateMode, optional) –

  Deprecated. Use update_on instead. Defines how the grid will send results back to Streamlit; either a string, one or a combination of:

  • GridUpdateMode.NO_UPDATE

  • GridUpdateMode.MANUAL

  • GridUpdateMode.VALUE_CHANGED

  • GridUpdateMode.SELECTION_CHANGED

  • GridUpdateMode.FILTERING_CHANGED

  • GridUpdateMode.SORTING_CHANGED

  • GridUpdateMode.MODEL_CHANGED

  When using manual a save button will be drawn on top of grid. modes can be combined with bitwise OR operator |, for instance:

  • GridUpdateMode = VALUE_CHANGED | SELECTION_CHANGED | FILTERING_CHANGED | SORTING_CHANGED

  Defaults to GridUpdateMode.MODEL_CHANGED

• data_return_mode (st_aggrid.shared.DataReturnMode, optional) –

  Defines how the data will be retrieved from components client side. One of:

  • DataReturnMode.AS_INPUT -> Returns grid data as inputed. Includes cell editions

  • DataReturnMode.FILTERED -> Returns filtered grid data, maintains input order

  • DataReturnMode.FILTERED_AND_SORTED -> Returns grid data filtered and sorted

  Defaults to DataReturnMode.AS_INPUT.

• allow_unsafe_jscode (bool, optional) – Allows jsCode to be injected in gridOptions. Defaults to False.

• enable_enterprise_modules (bool, optional) – Loads Ag-Grid enterprise modules (check licensing). Defaults to False.

• license_key (str, optional) – License key to use for enterprise modules. Defaults to None

• try_to_convert_back_to_original_types (bool, optional) – Attempts to convert data retrieved from the grid to original types. Defaults to True.

• conversion_errors (str, optional) –

  Behaviour when conversion fails. One of:

  • 'raise' -> invalid parsing will raise an exception.

  • 'coerce' -> then invalid parsing will be set as NaT/NaN.

  • 'ignore' -> invalid parsing will return the input.

  Defaults to 'coerce'.

• reload_data (bool, optional) – Force AgGrid to reload data using api calls. Should be False on most use cases. Default False

• columns_state (List, optional) – Column state to be applied to the grid. Defaults to None

• filter_state (Dict, optional) – Filter state to be applied to the grid. Defaults to None

• theme (str, optional) –

  theme used by ag-grid. One of:

  • 'streamlit' -> follows default streamlit colors

  • 'light' -> ag-grid balham-light theme

  • 'dark' -> ag-grid balham-dark theme

  • 'blue' -> ag-grid blue theme

  • 'fresh' -> ag-grid fresh theme

  • 'material' -> ag-grid material theme

  By default 'light'

• custom_css (dict, optional) – Custom CSS rules to be added to the component’s iframe. Defaults to None.

• use_legacy_selected_rows (bool, optional) – Use frontend value of 'selectedRows' instead of 'selectedItems'. Defaults to False.

• key (Any, optional) – Streamlit’s key argument. Check Streamlit’s documentation. Defaults to None.

• update_on (List[str | Tuple[str, int]], optional) –

  Defines the events that will trigger a refresh and grid return on Streamlit app. Valid string named events are listed in https://www.ag-grid.com/javascript-data-grid/grid-events/. If a tuple[string, int] is present on the list, that event will be debounced by x milliseconds. For instance:

  • if update_on = ['cellValueChanged', ("columnResized", 500)]

  Grid will return when cell values are changed AND when columns are resized, however the later will be debounced by 500 ms. More information about debounced functions here: https://www.freecodecamp.org/news/javascript-debounce-example/

• enable_quicksearch (bool, optional) – Adds a quicksearch text field on top of grid. Defaults to False

• excel_export_mode (st_aggrid.shared.ExcelExportMode, optional) –

  Defines how Excel Export integration behaves.

  • NONE -> Nothing Changes. Default grid behaviour.

  • MANUAL -> Adds a download button on grid’s top that triggers download.

  • FILE_BLOB_IN_GRID_RESPONSE -> include in grid’s return an ExcelBlob Property with file binary encoded as B64 String

  • TRIGGER_DOWNLOAD_AFTER_REFRESH -> Triggers file download before returning results to streamlit.

  • SHEET_BLOB_IN_GRID_RESPONSE -> include in grid’s return a SheetlBlob Property with sheet binary encoded as B64 String. Meant to be used with MULTIPLE

  • MULTIPLE_SHEETS -> Same as TRIGGER_DOWNLOAD_AFTER_REFRESH but will include b64 encoded SHEETS returned with SHEET_BLOB_IN_GRID_RESPONSE and supplied to grid’s call using excel_export_extra_sheets parameter.

• excel_export_multiple_sheet_params (Mapping, optional) – Defaults to None

• **default_column_parameters (Dict, optional) – Other parameters will be passed as key:value pairs on gridOptions defaultColDef.

Returns:

A dictionary with grid’s data is in dictionary’s 'data' key. Other keys may be present depending on gridOptions parameters

Return type:

st_aggrid.AgGridReturn

class st_aggrid.AgGridReturn(data: ~pandas.core.frame.DataFrame | str | None = None, selected_rows: ~typing.List[~typing.Mapping] = <factory>, columns_state: ~typing.List | None = None, excel_blob: ~typing.Any | None = None, filter_state: ~typing.Dict | None = None)

Class to hold AgGrid call return

Variables:

• data – data displayed by AgGrid

• selected_rows – rows selected in AgGrid

• columns_state – state of AgGrid columns

• excel_blob – Excel blob

• filter_state – state of AgGrid filter