table¶
Displays a data set as tabular data.
Properties¶
Name | Type | Default | Description |
---|---|---|---|
(★) |
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.
|
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. |
apply[column_name] |
str | "first" | The name of the aggregation function to use. |
style |
str | Allows the styling of table lines. |
|
style[column_name] |
str | Allows the styling of table cells. |
|
tooltip |
str | The name of the function that must return a tooltip text for a cell. |
|
tooltip[column_name] |
str | The name of the function that must return a tooltip text for a cell. |
|
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.
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.
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.
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.
|
|
size |
str | "small" | The size of the rows. |
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. |
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. |
|
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:
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
<|{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
<|{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
<|{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
<|{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
<|{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
<|{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), andlast
. - 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
<|{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
<|{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'}" />