Getting Started
This guide shows how to get started with AG Grid, and demonstrates some of the grid’s key features.
A basic Dash AG Grid contains column definitions, columnDefs, which define the grid’s columns and how they are displayed and behave, and the grid’s data, rowData.
In this example, we create a grid using the AgGrid component. Our columnDefs are written out in full and then passed to the grid.
from dash import Dash, html
import dash_ag_grid as dag
import pandas as pd
df = pd.read_csv("https://raw.githubusercontent.com/plotly/datasets/master/wind_dataset.csv")
app = Dash(__name__)
columnDefs = [
{ 'field': 'direction' },
{ 'field': 'strength' },
{ 'field': 'frequency'},
]
grid = dag.AgGrid(
id="get-started-example-basic",
rowData=df.to_dict("records"),
columnDefs=columnDefs,
)
app.layout = html.Div([grid])
if __name__ == "__main__":
app.run(debug=True)
The previous example showed the columnDefs written out in full. You can also extract the required information from the dataframe’s column names:
from dash import Dash, html
import dash_ag_grid as dag
import pandas as pd
df = pd.read_csv("https://raw.githubusercontent.com/plotly/datasets/master/wind_dataset.csv")
app = Dash(__name__)
grid = dag.AgGrid(
id="get-started-example-basic-df",
rowData=df.to_dict("records"),
columnDefs=[{"field": i} for i in df.columns],
)
app.layout = html.Div([grid])
if __name__ == "__main__":
app.run(debug=True)
For more on column definitions see the Column Definitions page and the Updating Column Definitions page.
Headers
Note how in the first example above, when you provide field names, the grid capitalizes the first letter when displaying the header name. You can also specify a header name in the column definitions, if you don’t want it to be created based on the field name. In this example, we specify a headerName for the second and third columns.
from dash import Dash, html
import dash_ag_grid as dag
import pandas as pd
df = pd.read_csv("https://raw.githubusercontent.com/plotly/datasets/master/gapminder2007.csv")
app = Dash(__name__)
columnDefs = [
{ 'field': 'country' },
{ 'field': 'pop', 'headerName': 'Population'},
{ 'field': 'lifeExp', 'headerName': 'Life Expectancy'},
]
grid = dag.AgGrid(
id="getting-started-headers",
rowData=df.to_dict("records"),
columnDefs=columnDefs,
)
app.layout = html.Div([grid])
if __name__ == "__main__":
app.run(debug=True)
There are many other ways to configure headers. For details on advanced options, including adding tooltips to headers, see the Column Headers page.
Column Filtering
Allow a user of the grid to filter a column by enabling filtering on it. In this example, we enable filtering on the first and last columns. Hover over a column header and select the icon that appears to see filtering options.
from dash import Dash, html
import dash_ag_grid as dag
import pandas as pd
df = pd.read_csv("https://raw.githubusercontent.com/plotly/datasets/master/gapminder2007.csv")
app = Dash(__name__)
columnDefs = [
{ 'field': 'country', 'filter': True },
{ 'field': 'pop', 'headerName': 'Population'},
{ 'field': 'lifeExp', 'headerName': 'Life Expectancy', 'filter': True },
]
grid = dag.AgGrid(
id="getting-started-filter",
rowData=df.to_dict("records"),
columnDefs=columnDefs,
)
app.layout = html.Div([grid])
if __name__ == "__main__":
app.run(debug=True)
See the column filtering page for more examples.
Row Sorting
As with column filtering, you can enable sorting on a column’s definition so users can sort the rows based on that column. This example makes the first and last columns sortable.
from dash import Dash, html
import dash_ag_grid as dag
import pandas as pd
df = pd.read_csv("https://raw.githubusercontent.com/plotly/datasets/master/gapminder2007.csv")
app = Dash(__name__)
columnDefs = [
{ 'field': 'country', 'sortable': True },
{ 'field': 'pop', 'headerName': 'Population'},
{ 'field': 'lifeExp', 'headerName': 'Life Expectancy', 'sortable': True },
]
grid = dag.AgGrid(
id="getting-started-sort",
rowData=df.to_dict("records"),
columnDefs=columnDefs,
)
app.layout = html.Div([grid])
if __name__ == "__main__":
app.run(debug=True)
See the row sorting page for more examples.
Themes
You can style your grid with a theme. AG Grid includes the following themes: ag-theme-alpine, ag-theme-alpine-dark, ag-theme-balham, ag-theme-balham-dark, ag-theme-material, and ag-bootstrap.
The grid uses ag-theme-alpine by default. To use any other theme, set it using className. For example, className="ag-theme-balham", like in the following example.
from dash import Dash, html
import dash_ag_grid as dag
import plotly.express as px
app = Dash(__name__)
df = px.data.gapminder()
df = df[['country', 'continent', 'year', 'pop']]
app.layout = html.Div(
[
dag.AgGrid(
id="getting-started-themes-example",
columnDefs= [{"headerName": x, "field": x, } for x in df.columns],
rowData= df.to_dict('records'),
className="ag-theme-balham",
columnSize="sizeToFit",
style={'height': '250px'}
),
]
)
if __name__ == "__main__":
app.run(debug=True)
For more on themes, including how to configure custom themes, see the themes page.
Pagination
By default, the grid uses a vertical scroll. You can reduce the amount of scrolling required by adding pagination. To add pagination, set pagination to True:
from dash import Dash, html
import dash_ag_grid as dag
import pandas as pd
df = pd.read_csv("https://raw.githubusercontent.com/plotly/datasets/master/gapminder2007.csv")
app = Dash(__name__)
columnDefs = [
{ 'field': 'country' },
{ 'field': 'pop', 'headerName': 'Population'},
{ 'field': 'lifeExp', 'headerName': 'Life Expectancy'},
]
grid = dag.AgGrid(
id="getting-started-pagination",
rowData=df.to_dict("records"),
columnDefs=columnDefs,
dashGridOptions={'pagination':True},
)
app.layout = html.Div([grid])
if __name__ == "__main__":
app.run(debug=True)
For more on pagination options, including how to set the page size, see the pagination page.
With Callbacks
You can use callbacks to update the grid based on user input. In this example, when the user selects the button, the columnDefs on the grid update.
from dash import Dash, html, callback, Input, Output
import dash_ag_grid as dag
import pandas as pd
df = pd.read_csv("https://raw.githubusercontent.com/plotly/datasets/master/gapminder2007.csv")
app = Dash(__name__)
all_columns = [
{ 'field': 'country' },
{ 'field': 'pop'},
{ 'field': 'continent' },
{ 'field': 'lifeExp'},
{ 'field': 'gdpPercap'},
]
two_columns = [
{ 'field': 'country' },
{ 'field': 'pop'},
]
grid = dag.AgGrid(
id="grid-callback-example",
rowData=df.to_dict("records"),
)
app.layout = html.Div(
[
html.Button(id='update-columns', children='Update columns'),
grid,
]
)
@callback(
Output("grid-callback-example", "columnDefs"),
Input("update-columns", "n_clicks")
)
def update_columns(n_clicks):
if n_clicks and n_clicks % 2 != 0:
return two_columns
return all_columns
if __name__ == "__main__":
app.run(debug=True)
For more examples on updating
columnDefs, see the updating column definitions page. Throughout the docs, you’ll find more examples of using callbacks to update the grid, and to perform other actions, for example, to download the grid to a CSV file.
Using AG Grid Enterprise
AG Grid offers both community and enterprise versions. See the AG Grid docs for details on purchasing a license key.
To use an AG Grid Enterprise license key with Dash AG Grid, include it with licenseKey=<your_license_key>. and set enableEnterpriseModules=True:
dag.AgGrid(
enableEnterpriseModules=True,
licenseKey=<your_license_key>,
columnDefs=ColumnDefs,
rowData=rowData
)
For examples with enterprise features, see Sparklines, Master Detail, Row Aggregation with Conditional Formatting, Aggregation with Custom Functions, Row Groupings, Sidebar, Pivot, and Tree Data.