`table`¶

Displays a data set as tabular data.

Properties¶

Name	Type	Default	Description
`data`^(★)	dynamic(any)	Required	The data to be represented in this table.
`page_size`	int	100	For a paginated table, the number of visible rows.
`allow_all_rows`	bool	False	For a paginated table, adds an option to show all the rows.
`show_all`	bool	False	For a paginated table, show all the rows.
`auto_loading`	bool	False	If True, the data will be loaded on demand.
`width[column_name]`	str		The width, in CSS units, of the indicated column.
`selected`	list[int]\|str		The list of the indices of the rows to be displayed as selected.
`page_size_options`	list[int]\|str	[50, 100, 500]	The list of available page sizes that users can choose from.
`columns`	str\|list[str]\|dict[str, dict[str, str\|int]]	shows all columns when empty	The list of the column names to display. str: Semicolon (';')-separated list of column names. list[str]: The list of column names. dict: A dictionary with entries matching: {"col name": {format: "format", index: 1}}. if index is specified, it represents the display order of the columns. If index is not specified, the list order defines the index. If format is specified, it is used for numbers or dates.
`date_format`	str	"MM/dd/yyyy"	The date format used for all date columns when the format is not specifically defined.
`number_format`	str		The number format used for all number columns when the format is not specifically defined.
`group_by[column_name]`	bool	False	Indicates, if True, that the given column can be aggregated. See below for details.
`apply[column_name]`	str	"first"	The name of the aggregation function to use. This is used only if group_by[column_name] is set to True. See below for details.
`style`	str		Allows the styling of table lines. See below for details.
`style[column_name]`	str		Allows the styling of table cells. See below for details.
`tooltip`	str		The name of the function that must return a tooltip text for a cell. See below for details.
`tooltip[column_name]`	str		The name of the function that must return a tooltip text for a cell. See below for details.
`width`	str	"100%"	The width, in CSS units, of this table control.
`height`	str	"80vh"	The height, in CSS units, of this table control.
`filter`	bool	False	Indicates, if True, that all columns can be filtered.
`filter[column_name]`	bool	False	Indicates, if True, that the indicated column can be filtered.
`nan_value`	str	""	The replacement text for NaN (not-a-number) values.
`nan_value[column_name]`	str	""	The replacement text for NaN (not-a-number) values for the indicated column.
`editable`	dynamic(bool)	True	Indicates, if True, that all columns can be edited.
`editable[column_name]`	bool	editable	Indicates, if False, that the indicated column cannot be edited when editable is True.
`on_edit`	Callback		The name of a function that is triggered when a cell edition is validated. All parameters of that function are optional: state (`State`): the state instance. var_name (str): the name of the tabular data variable. action (str): the name of the action that provoked the change. payload (dict): the details on this callback's invocation. This dictionary has the following keys: index (int): the row index. col (str): the column name. value (any): the new cell value cast to the type of the column. user_value (str): the new cell value, as it was provided by the user. tz (str): the timezone if the column type is date. If this property is not set, the user cannot edit cells.
`on_delete`	str		The name of a function that is triggered when a row is deleted. All parameters of that function are optional: state (`State`): the state instance. var_name (str): the name of the tabular data variable. action (str): the name of the action that provoked the change. payload (dict): the details on this callback's invocation. This dictionary has the following keys: index (int): the row index. If this property is not set, the user cannot delete rows.
`on_add`	str		The name of a function that is triggered when the user requests a row to be added. All parameters of that function are optional: state (`State`): the state instance. var_name (str): the name of the tabular data variable. action (str): the name of the action that provoked the change. payload (dict): the details on this callback's invocation. This dictionary has the following keys: index (int): the row index. If this property is not set, the user cannot add rows.
`on_action`	str		The name of a function that is triggered when the user selects a row. All parameters of that function are optional: state (`State`): the state instance. var_name (str): the name of the tabular data variable. action (str): the name of the action that provoked the change. payload (dict): the details on this callback's invocation. This dictionary has the following keys: index (int): the row index. .
`size`	str	"small"	The size of the rows. Valid values are "small" and "medium".
`rebuild`	dynamic(bool)	False	If set to True, this allows to dynamically refresh the columns.
`active`	dynamic(bool)	True	Indicates if this component is active. An inactive component allows no user interaction.
`id`	str		The identifier that will be assigned to the rendered HTML component.
`properties`	dict[str, any]		Bound to a dictionary that contains additional properties for this element.
`class_name`	dynamic(str)		The list of CSS class names that will be associated with the generated HTML Element. These class names will be added to the default `taipy-<element_type>`.
`hover_text`	dynamic(str)		The information that is displayed when the user hovers over this element.

^(★)data is the default property for this visual element.

Details¶

Data types¶

All the data sets represented in the table control must be assigned to its data property.

The supported types for the data property are:

A list of values:
When receiving a data that is just a series of values, the table is made of a single column holding the values at the corresponding index. The column name is then "0".
A Pandas DataFrame:
Taipy tables then use the same column names as the DataFrame's.
A dictionary:
The value is converted into a Pandas DataFrame where each key/value pair is converted to a column named key and the associated value. Note that this will work only when all the values of the dictionary keys are series that have the same length.
A list of lists of values:
All the lists must be the same length. The table control creates one row for each list in the collection.
A Numpy series:
Taipy internally builds a Pandas DataFrame with the provided data.

Display modes¶

The table component supports three display modes:

paginated: you can choose the page size and page size options. The allow_all_rows property makes it possible to add an option to show a page with all rows.
unpaginated: all rows and no page are shown. That is the setting when the show_all property is set to True.
auto_loading: the pages are loaded on demand depending on the visible area. That is the behavior when the auto_loading property is set to True.

The rebuild property¶

When the application modifies the value of a dynamic property, the impact of the change is immediately reflected on the application page. However, changing the value of properties that are not dynamic requires that the user refreshes the page manually (or that the application explicitly calls navigate() with the force parameter set to True). This is due to the fact that the entire front-end component must be entirely re-generated to reflect its new settings based on the property values.
The table control provides the rebuild property that, when set to True, triggers the rebuilding of the table front-end component and refreshes the page.
Note that this mechanism may hurt the user experience because rebuilding the entire component can be a somewhat complex operation.

Here is a situation where you may need to use rebuild: your application displays a table, and you want to provide a way to interactively change the order of its columns.
Here is what the application code would look like:

table.py

from taipy.gui import Gui

# x: [1..5]
x_range = range(1, 6)
data = {
    "X": x_range,
    "Y": [x*x for x in x_range]
}

column_orders = [("X;Y", "Squared"), ("Y;X", "Square root")]
columns = column_orders[0]

page = """
<|{data}|table|columns={columns[0]}|show_all|>

<|{columns}|toggle|lov={column_orders}|>
"""

Gui(page=page).run()

The table displays two columns of data, one column holding the square value of the other. When you run this application, here is what the page looks like:

A toggle button lets the user choose whether to represent, in the second column, the square of the value in the first column or the other way around.
To implement this, the code is setting the value "X;Y" or "Y;X" to the property columns.
Here is what the application looks like just after the user has changed the value of the toggle button:

We can see that although the value for the toggle button was properly updated, the table has not rearranged its columns. That is because the columns property is not dynamic.

Setting the rebuild property to True allows for updating the table on the fly: let's change the table's Markdown definition to:

<|{data}|table|columns={columns[0]}|show_all|rebuild|>

If you run the application again, and select the alternative column order in the toggle button, here is what the page looks like:

Now the table properly reflects the value of the columns property and no manual refresh was needed.

Make sure, when you are using the rebuild property, that no performance impact is so bad that it would ruin the user experience.

Styling¶

All the table controls are generated with the "taipy-table" CSS class. You can use this class name to select the tables on your page and apply style.

Stylekit support¶

The Stylekit provides a CSS custom property:

--table-stripe-opacity
This property contains the opacity applied to odd lines of tables.
The default value is 0.5.

The Stylekit also provides specific CSS classes that you can use to style tables:

header-plain
Adds a plain and contrasting background color to the table header.
rows-bordered
Adds a bottom border to each row.
rows-similar
Removes the even-odd striped background so all rows have the same background.

Dynamic styling¶

You can modify the style of entire rows or specific table cells based on any criteria, including the table data itself.

When Taipy creates the rows and the cells, it can add a specific CSS class to the generated elements. This class name is the string returned by the function set to the style property for entire rows, or style[column_name] for specific cells.

The signature of this function depends on which style property you use:

style: this applies to entire rows.
The given function expects three optional parameters:
- state: the current state
- index: the index of the row in this table
- row: all the values for this row
style[column_name]: this applies to a specific cell.
The given function expects five optional parameters:
- state: the current state
- value: the value of the cell
- index: the index of the row in this table
- row: all the values for this row
- column_name: the name of the column for this cell

Based on these parameters, the function must return a string that defines a CSS class name that will be added to the CSS classes for this table row or this specific cell.
The example below shows how this works.

Usage¶

Show tabular data¶

Suppose you want to display the data set defined as follows:

# x_range = [-10, -6, -2, 2, 6, 10]
x_range = range(-10, 11, 4)

data = {
    "x": x_range,
    # y1 = x*x
    "y1": [x*x for x in x_range],
    # y2 = 100-x*x
    "y2": [100-x*x for x in x_range]
}

You can use the following control declaration to display all these numbers in a table:

Page content

MarkdownHTML

<|{data}|table|>

<taipy:table data="{data}" />

The resulting image looks like this:

Large data¶

The example above had only six lines of data. If we change the x_range definition to create far more data lines, we come up with a table with much more data to display:

# x_range = [-10, -9.98, ..., 9.98, 10.0] - 1000 x values
x_range = [round(20*i/1000-10, 2) for i in range(0, 1001)]

data = {
    "x": large_x_range,
    # y1 = x*x
    "y1": [round(x*x, 5) for x in large_x_range],
    # y2 = 100-x*x
    "y2": [round(100-x*x, 5) for x in large_x_range]
}

We can use the same table control definition:

Page content

MarkdownHTML

<|{data}|table|>

<taipy:table data="{data}" />

To get a rendering looking like this:

Only the first 100 rows (as indicated in the 'Rows per page' selector) are visible.
The table scroll bar lets you navigate across the 100 first rows.
You can change how many rows are displayed simultaneously using the page_size and page_size_options properties.

If you want to display all the rows at the same time, you can change the control definition to add the *show_all:

Page content

MarkdownHTML

<|{data}|table|show_all|>

<taipy:table data="{data}" show_all="true"/>

Now the table displays all the data rows, and the scrollbar lets you navigate among all of them:

Setting the allow_all_rows property to True for a paginated table adds the 'All' option to the page size options, so the user can switch from one mode to the other.

Show specific columns¶

If you want to display a specific set of columns, you can use the columns property to indicate what columns should be displayed.

Here is how you would define the table control if you want to hide the column y2 from the examples above:

Page content

MarkdownHTML

<|{data}|table|columns=x;y1|>

<taipy:table columns="x;y1">{data}</taipy:table>

And the y2 column is not displayed any longer:

Styling rows¶

To give a specific style to a table row, you will use the style property.
This property holds a function that is invoked when each row is rendered, and it must return the name of a style, defined in CSS.

Here is how a row styling function can be defined:

def even_odd_style(_1, index, _2):
    if index % 2:
        return "blue-cell"
    else:
        return "red-cell"

We only use the second parameter since, in this straightforward case, we do not need the application state (first parameter) or the values in the row (third parameter).
Based on the row index (received in index), this function returns the name of the style to apply to the row: "blue-cell" if the index is odd, "red-cell" if it is even.

We need to define what these style names mean. This is done in a CSS stylesheet, where the following CSS content would appear:

.blue-cell>td {
    color: white;
    background-color: blue;
}
.red-cell>td {
    color: yellow;
    background-color: red;
}

Note that the style selectors use the CSS child combinator selector ">" to target elements that hold a td element (the cells themselves).

To use this style, we can adjust the control definition used above so it looks like this:

Page content

MarkdownHTML

<|{data}|table|style=even_odd_style|>

<taipy:table data="{data}" style="even_odd_style" />

The resulting display will be what we expected:

Note that the styling function is so simple that we could have made it a lambda, directly in the control definition:

Alternative page content

MarkdownHTML

<|{data}|table|style={lambda s, idx, r: "blue-cell" if idx % 2 == 0 else "red-cell"}|>

<taipy:table data="{data}" style="{lambda s, idx, r: "blue-cell" if idx % 2 == 0 else "red-cell"}" />

Aggregation¶

To get the aggregation functionality in your table, you must indicate which columns can be aggregated and how to perform the aggregation.

This is done using the indexed group_by and apply properties.

The group_by[column_name] property, when set to True indicates that the column column_name can be aggregated.

The function provided in the apply[column_name] property indicates how to perform this aggregation. The value of this property, which is a string, can be:

A built-in function. Available predefined functions are the following: count, sum, mean, median, min, max, std, first (the default value), and last.
The name of a user-defined function or a lambda function.
This function receives a single parameter which is the series to aggregate, and it must return a scalar value that would result from the aggregation.

Page content

MarkdownHTML

<|{data}|table|group_by[Group column]|apply[Apply column]=count|>

<taipy:table data="{data}" group_by[Group column]="True" apply[Apply column]="count" />

Cell tooltips¶

You can specify a tooltip for specific table cells.

When Taipy creates the cells, it can add a specific tooltip that you would have set as the return value of the function set to the tooltip or tooltip[column_name] properties.

The signature of this function expects five optional parameters: - state: the current state. - value: the value of the cell. - index: the index of the row in this table. - row: all the values for this row. - column_name: the name of the column for this cell.

Based on these parameters, the function must return a string that defines a tooltip used as the cell's tooltip text.

Page content

MarkdownHTML

<|{data}|table|tooltip={lambda state, val, idx: "A tooltip" if idx % 2 == 0 else "Another tooltip"}|>

<taipy:table data="{data}" tooltip="{lambda state, idx, col: 'A tooltip' if idx % 2 == 0 else 'Another tooltip'}" />

table¶

Properties¶

Details¶

Data types¶

Display modes¶

The rebuild property¶

Styling¶

Stylekit support¶

Dynamic styling¶

Usage¶

Show tabular data¶

Large data¶

Show specific columns¶

Styling rows¶

Aggregation¶

Cell tooltips¶

`table`¶