Tabulator#

Download this notebook from GitHub (right-click to download).

import datetime as dt
import numpy as np
import pandas as pd
import panel as pn

pn.extension('tabulator', css_files=[pn.io.resources.CSS_URLS['font-awesome']])

The Tabulator widget allows displaying and editing a pandas DataFrame. The Tabulator is a largely backward compatible replacement for the DataFrame widget and will eventually replace it. It is built on the Tabulator library, which provides for a wide range of features.

For more information about listening to widget events and laying out widgets refer to the widgets user guide. Alternatively you can learn how to build GUIs by declaring parameters independently of any specific widgets in the param user guide. To express interactivity entirely using Javascript without the need for a Python server take a look at the links user guide.

Parameters:#

For layout and styling related parameters see the customization user guide.

Core#

  • aggregators (dict): A dictionary mapping from index name to an aggregator to be used for hierarchical multi-indexes (valid aggregators include ‘min’, ‘max’, ‘mean’ and ‘sum’). If separate aggregators for different columns are required the dictionary may be nested as {index_name: {column_name: aggregator}}

  • buttons (dict): A dictionary of buttons to add to the table mapping from column name to the HTML contents of the button cell, e.g. {'print': '<i class="fa fa-print"></i>'}. Buttons are added after all data columns.

  • configuration (dict): A dictionary mapping used to specify tabulator options not explicitly exposed by panel.

  • editors (dict): A dictionary mapping from column name to a bokeh CellEditor instance or tabulator editor specification.

  • embed_content (boolean): Whether to embed the row_content or to dynamically fetch it when a row is expanded.

  • expanded (list): The currently expanded rows as a list of integer indexes.

  • filters (list): A list of client-side filter definitions that are applied to the table.

  • formatters (dict): A dictionary mapping from column name to a bokeh CellFormatter instance or tabulator formatter specification.

  • groupby (list): Groups rows in the table by one or more columns.

  • header_align (dict or str): A mapping from column name to header alignment or a fixed header alignment, which should be one of 'left', 'center', 'right'.

  • header_filters (boolean/dict): A boolean enabling filters in the column headers or a dictionary providing filter definitions for specific columns.

  • hierarchical (boolean, default=False): Whether to render multi-indexes as hierarchical index (note hierarchical must be enabled during instantiation and cannot be modified later)

  • hidden_columns (list): List of columns to hide.

  • layout (str, default='fit_data_table'): Describes the column layout mode with one of the following options 'fit_columns', 'fit_data', 'fit_data_stretch', 'fit_data_fill', 'fit_data_table'.

  • frozen_columns (list): List of columns to freeze, preventing them from scrolling out of frame. Column can be specified by name or index.

  • frozen_rows: (list): List of rows to freeze, preventing them from scrolling out of frame. Rows can be specified by positive or negative index.

  • page (int, default=1): Current page, if pagination is enabled.

  • page_size (int, default=20): Number of rows on each page, if pagination is enabled.

  • pagination (str, default=None): Set to 'local or 'remote' to enable pagination; by default pagination is disabled with the value set to None.

  • row_content (callable): A function that receives the expanded row as input and should return a Panel object to render into the expanded region below the row.

  • row_height (int, default=30): The height of each table row.

  • selection (list): The currently selected rows as a list of integer indexes.

  • selectable (boolean or str or int, default=True): Defines the selection mode:

    • True Selects rows on click. To select multiple use Ctrl-select, to select a range use Shift-select

    • False Disables selection

    • 'checkbox' Adds a column of checkboxes to toggle selections

    • 'checkbox-single' Same as ‘checkbox’ but header does not alllow select/deselect all

    • 'toggle' Selection toggles when clicked

    • int The maximum number of selectable rows.

  • selectable_rows (callable): A function that should return a list of integer indexes given a DataFrame indicating which rows may be selected.

  • show_index (boolean, default=True): Whether to show the index column.

  • sorters (list): A lisst of sorter definitions mapping where each item should declare the column to sort on and the direction to sort, e.g. [{'field': 'column_name', 'dir': 'asc'}, {'field': 'another_column', 'dir': 'desc'}].

  • text_align (dict or str): A mapping from column name to alignment or a fixed column alignment, which should be one of 'left', 'center', 'right'.

  • theme (str, default='simple'): The CSS theme to apply (note that changing the theme will restyle all tables on the page), which should be one of 'default', 'site', 'simple', 'midnight', 'modern', 'bootstrap', 'bootstrap4', 'materialize', 'bulma', 'semantic-ui', or 'fast'.

  • titles (dict): A mapping from column name to a title to override the name with.

  • value (pd.DataFrame): The pandas DataFrame to display and edit

  • widths (dict): A dictionary mapping from column name to column width in the rendered table.

Display#

  • disabled (boolean): Whether the cells are editable

  • name (str): The title of the widget

Properties#

  • current_view (DataFrame): The current view of the table that is displayed, i.e. after sorting and filtering are applied

  • selected_dataframe (DataFrame): A DataFrame reflecting the currently selected rows.

Callbacks#

  • on_click: Allows registering callbacks which are given CellClickEvent objects containing the column, row and value of the clicked cell.

  • on_edit: Allows registering callbacks which are given TableEditEvent objects containing the column, row, value and old value.

The Tabulator widget renders a DataFrame using an interactive grid, which allows directly editing the contents of the dataframe in place, with any changes being synced with Python. The Tabulator will usually determine the appropriate formatter appropriately based on the type of the data:

df = pd.DataFrame({
    'int': [1, 2, 3],
    'float': [3.14, 6.28, 9.42],
    'str': ['A', 'B', 'C'],
    'bool': [True, False, True],
    'date': [dt.date(2019, 1, 1), dt.date(2020, 1, 1), dt.date(2020, 1, 10)],
    'datetime': [dt.datetime(2019, 1, 1, 10), dt.datetime(2020, 1, 1, 12), dt.datetime(2020, 1, 10, 13)]
}, index=[1, 2, 3])

df_widget = pn.widgets.Tabulator(df, buttons={'Print': "<i class='fa fa-print'></i>"})
df_widget

Formatters#

By default the widget will pick bokeh CellFormatter and CellEditor types appropriate to the dtype of the column. These may be overriden by explicit dictionaries mapping from the column name to the editor or formatter instance. For example below we create a SelectEditor instance to pick from four options in the str column and a NumberFormatter to customize the formatting of the float values:

from bokeh.models.widgets.tables import NumberFormatter, BooleanFormatter

bokeh_formatters = {
    'float': NumberFormatter(format='0.00000'),
    'bool': BooleanFormatter(),
}

pn.widgets.Tabulator(df, formatters=bokeh_formatters)

The list of valid Bokeh formatters includes:

However in addition to the formatters exposed by Bokeh it is also possible to provide valid formatters built into the Tabulator library. These may be defined either as a string or as a dictionary declaring the ‘type’ and other arguments, which are passed to Tabulator as the formatterParams:

tabulator_formatters = {
    'float': {'type': 'progress', 'max': 10},
    'bool': {'type': 'tickCross'}
}

pn.widgets.Tabulator(df, formatters=tabulator_formatters)

The list of valid Tabulator formatters can be found in the Tabulator documentation.

Editors#

Just like the formatters, the Tabulator will natively understand the Bokeh Editor types. However, in the background it will replace most of them with equivalent editors natively supported by the tabulator library:

from bokeh.models.widgets.tables import CheckboxEditor, NumberEditor, SelectEditor, DateEditor, TimeEditor

bokeh_editors = {
    'float': NumberEditor(),
    'bool': CheckboxEditor(),
    'str': SelectEditor(options=['A', 'B', 'C', 'D']),
}

pn.widgets.Tabulator(df[['float', 'bool', 'str']], editors=bokeh_editors)

Therefore it is often preferable to use one of the Tabulator editors directly. Setting the editor of a column to None makes that column non-editable. Note that in addition to the standard Tabulator editors the Tabulator widget also supports 'date' and 'datetime' editors:

from bokeh.models.widgets.tables import CheckboxEditor, NumberEditor, SelectEditor

bokeh_editors = {
    'int': None,
    'float': {'type': 'number', 'max': 10, 'step': 0.1},
    'bool': {'type': 'tickCross', 'tristate': True, 'indeterminateValue': None},
    'str': {'type': 'autocomplete', 'values': True},
    'date': 'date',
    'datetime': 'datetime'
}

edit_table = pn.widgets.Tabulator(df, editors=bokeh_editors)

edit_table

When editing a cell the data stored on the Tabulator.value is updated and you can listen to any changes using the usual .param.watch(callback, 'value') mechanism. However if you need to know precisely which cell was changed you may also attach an on_edit callback which will be passed a TableEditEvent containing the:

  • column: Name of the edited column

  • row: Integer index of the edited row

  • value: The updated value

edit_table.on_edit(lambda e: print(e.column, e.row, e.value))

Column layouts#

By default the DataFrame widget will adjust the sizes of both the columns and the table based on the contents, reflecting the default value of the parameter: layout="fit_data_table". Alternative modes allow manually specifying the widths of the columns, giving each column equal widths, or adjusting just the size of the columns.

Manual column widths#

To manually adjust column widths provide explicit widths for each of the columns:

custom_df = pd._testing.makeMixedDataFrame()

pn.widgets.Tabulator(custom_df, widths={'index': 70, 'A': 50, 'B': 50, 'C': 70, 'D': 130})

You can also declare a single width for all columns this way:

pn.widgets.Tabulator(custom_df, widths=130)

or even use percentage widths:

pn.widgets.Tabulator(custom_df, widths={'index': '5%', 'A': '15%', 'B': '15%', 'C': '25%', 'D': '40%'}, sizing_mode='stretch_width')

Autosize columns#

To automatically adjust the columns dependending on their content set layout='fit_data':

pn.widgets.Tabulator(custom_df, layout='fit_data', width=400)

To ensure that the table fits all the data but also stretches to fill all the available space, set layout='fit_data_stretch':

pn.widgets.Tabulator(custom_df, layout='fit_data_stretch', width=400)

The 'fit_data_fill' option on the other hand won’t stretch the last column but still fill the space:

pn.widgets.Tabulator(custom_df, layout='fit_data_fill', width=400)

Perhaps the most useful of these options is layout='fit_data_table' (and therefore the default) since this will automatically size both the columns and the table:

pn.widgets.Tabulator(custom_df, layout='fit_data_table')

Equal size#

The simplest option is simply to allocate each column equal amount of size:

pn.widgets.Tabulator(custom_df, layout='fit_columns', width=650)

Alignment#

The content of a column or its header can be horizontally aligned with text_align and header_align. These two parameters accept either a string that globally defines the alignment or a dictionnary that declares which particular columns are meant to be aligned and how.

pn.widgets.Tabulator(df, header_align='center', text_align={'str': 'right', 'bool': 'center'}, widths=200)

Styling#

The ability to style the contents of a table based on its content and other considerations is very important. Thankfully pandas provides a powerful styling API, which can be used in conjunction with the Tabulator widget. Specifically the Tabulator widget exposes a .style attribute just like a pandas.DataFrame which lets the user apply custom styling using methods like .apply and .applymap. For a detailed guide to styling see the Pandas documentation.

Here we will demonstrate with a simple example, starting with a basic table:

style_df = pd.DataFrame(np.random.randn(10, 5), columns=list('ABCDE'))
styled = pn.widgets.Tabulator(style_df)

Next we define two functions which apply styling cell-wise (color_negative_red) and column-wise (highlight_max), which we then apply to the Tabulator using the .style API and then display the styled table:

def color_negative_red(val):
    """
    Takes a scalar and returns a string with
    the css property `'color: red'` for negative
    strings, black otherwise.
    """
    color = 'red' if val < 0 else 'black'
    return 'color: %s' % color

def highlight_max(s):
    '''
    highlight the maximum in a Series yellow.
    '''
    is_max = s == s.max()
    return ['background-color: yellow' if v else '' for v in is_max]

styled.style.applymap(color_negative_red).apply(highlight_max)

styled

Theming#

The Tabulator library ships with a number of themes, which are defined as CSS stylesheets. For that reason changing the theme on one table will affect all Tables on the page and it will usually be preferable to see the theme once at the class level like this:

pn.widgets.Tabulator.theme = 'default'

For a full list of themes see the Tabulator documentation, however the default themes include:

  • 'simple'

  • 'default'

  • 'midnight'

  • 'site'

  • 'modern'

  • 'bootstrap'

  • 'bootstrap4'

  • 'materialize'

  • 'semantic-ui'

  • 'bulma'

Selection#

The selection parameter controls which rows in the table are selected and can be set from Python and updated by selecting rows on the frontend:

sel_df = pd.DataFrame(np.random.randn(10, 5), columns=list('ABCDE'))

select_table = pn.widgets.Tabulator(sel_df, selection=[0, 3, 7])
select_table

Once initialized, the selection parameter will return the integer indexes of the selected rows, while the selected_dataframe property will return a new DataFrame containing just the selected rows:

select_table.selection = [1, 4, 9]

select_table.selected_dataframe
A B C D E
1 -1.209382 1.048071 2.245985 -0.670312 -0.593414
4 0.205328 -0.549119 2.015053 0.300269 -0.249040
9 -0.801613 -0.054069 -0.749260 0.315804 -0.140001

The selectable parameter declares how the selections work.

  • True: Selects rows on click. To select multiple use Ctrl-select, to select a range use Shift-select

  • False: Disables selection

  • 'checkbox': Adds a column of checkboxes to toggle selections

  • 'checkbox-single': Same as 'checkbox' but disables (de)select-all in the header

  • 'toggle': Selection toggles when clicked

  • Any positive int: A number that sets the maximum number of selectable rows

pn.widgets.Tabulator(sel_df, selection=[0, 3, 7], selectable='checkbox')

Additionally we can also disable selection for specific rows by providing a selectable_rows function. The function must accept a DataFrame and return a list of integer indexes indicating which rows are selectable, e.g. here we disable selection for every second row:

pn.widgets.Tabulator(sel_df, selectable_rows=lambda df: list(range(0, len(df), 2)))

To trigger events based on an exact cell that was clicked you may also register an on_click callback which is called whenever a cell is clicked.

def click(event):
    print(f'Clicked cell in {event.column} column, row {event.row}')

select_table.on_click(click) 
# Optionally we can also limit the callback to a specific column
# select_table.on_click(click, column='A')

Freezing rows and columns#

Sometimes your table will be larger than can be displayed in a single viewport, in which case scroll bars will be enabled. In such cases, you might want to make sure that certain information is always visible. This is where the frozen_columns and frozen_rows options come in.

Frozen columns#

When you have a large number of columns and can’t fit them all on the screen you might still want to make sure that certain columns do not scroll out of view. The frozen_columns option makes this possible by specifying a list of columns that should be frozen, e.g. frozen_columns=['index'] will freeze the index column:

wide_df = pd._testing.makeCustomDataframe(10, 10, r_idx_names=['index'])

pn.widgets.Tabulator(wide_df, frozen_columns=['index'], width=400)

Frozen rows#

Another common scenario is when you have certain rows with special meaning, e.g. aggregates that summarize the information in the rest of the table. In this case you may want to freeze those rows so they do not scroll out of view. You can achieve this by setting a list of frozen_rows by integer index (which can be positive or negative, where negative values are relative to the end of the table):

date_df = pd._testing.makeTimeDataFrame().iloc[:10]
agg_df = pd.concat([date_df, date_df.median().to_frame('Median').T, date_df.mean().to_frame('Mean').T])
agg_df.index= agg_df.index.map(str)

pn.widgets.Tabulator(agg_df, frozen_rows=[-2, -1], width=400)

Row contents#

A table can only display so much information without becoming difficult to scan. We may want to render additional information to a table row to provide additional context. To make this possible you can provide a row_content function which is given the table row as an argument and should return a panel object that will be rendered into an expanding region below the row. By default the contents are fetched dynamically whenever a row is expanded, however using the embed_content parameter we can embed all the content.

Below we create a periodic table of elements where the Wikipedia page for each element will be rendered into the expanded region:

from bokeh.sampledata.periodic_table import elements

periodic_df = elements[['atomic number', 'name', 'atomic mass', 'metal', 'year discovered']].set_index('atomic number')

content_fn = lambda row: pn.pane.HTML(
    f'<iframe src="http://en.wikipedia.org/wiki/{row["name"]}?printable=yes" width="100%" height="300px"></iframe>',
    sizing_mode='stretch_width'
)

periodic_table = pn.widgets.Tabulator(
    periodic_df, height=500, layout='fit_columns', sizing_mode='stretch_width',
    row_content=content_fn, embed_content=True
)

periodic_table

The currently expanded rows can be accessed (and set) on the expanded parameter:

periodic_table.expanded

[]

Grouping#

Another useful option is the ability to group specific rows together, which can be achieved using groups parameter. The groups parameter should be composed of a dictionary mapping from the group titles to the column names:

pn.widgets.Tabulator(date_df, groups={'Group 1': ['A', 'B'], 'Group 2': ['C', 'D']})

Groupby#

In addition to grouping columns we can also group rows by the values along one or more columns:

from bokeh.sampledata.autompg import autompg

pn.widgets.Tabulator(autompg, groupby=['yr', 'origin'], height=240)

Hierarchical Multi-index#

The Tabulator widget can also render a hierarchical multi-index and aggregate over specific categories. If a DataFrame with a hierarchical multi-index is supplied and the hierarchical is enabled the widget will group data by the categories in the order they are defined in. Additionally for each group in the multi-index an aggregator may be provided which will aggregate over the values in that category.

For example we may load population data for locations around the world broken down by sex and age-group. If we specify aggregators over the ‘AgeGrp’ and ‘Sex’ indexes we can see the aggregated values for each of those groups (note that we do not have to specify an aggregator for the outer index since we specify the aggregators over the subgroups in this case the ‘Sex’):

from bokeh.sampledata.population import data as population_data 

pop_df = population_data[population_data.Year == 2020].set_index(['Location', 'AgeGrp', 'Sex'])[['Value']]

pn.widgets.Tabulator(value=pop_df, hierarchical=True, aggregators={'Sex': 'sum', 'AgeGrp': 'sum'}, height=400)