Quick Start

Installation

Install the table_widget package using pip:

pip install table_widget

Basic Usage

Create an Instance of the Table Widget:

[1]:

from table_widget import TableWidget
table = TableWidget()

Add Data to the Table

You can provide data either as a pandas.DataFrame or a dictionary of records.

[2]:

import pandas as pd

# Sample DataFrame
data = pd.DataFrame({
    "name": ["Alice", "Bob", "Charlie"],
    "score": [95, 87, 73],
    "comment": ["Excellent", "Good", "Needs Improvement"],
    "status": ["Active", "Inactive", "Active"],
})

# Define column metadata
columns = [
    {"field": "name", "headerName": "Name", "editable": False},
    {"field": "score", "headerName": "Score", "type": "number", "editable": True},
    {"field": "comment", "headerName": "Comment", "editable": True},
    {"field": "status", "headerName": "Status", "type": "singleSelect", "valueOptions": ["Active", "Inactive"], "editable": True},
]

# Load data into the table
table.from_data(data, columns=columns)
table

[2]:

Data format

The table widget provides predefined column types. By default, columns are treated as strings, meaning they will use string-based sorting and align content to the left. Some column types require specific value types for their cells.

Column Type

Required Value Type

Description

'string' (default)

string

Default type. Aligns content to the left and sorts lexically.

'number'

number

For numeric data. Aligns content to the right and sorts numerically.

'date'

Date() object

For date values. Enables date-based sorting.

'dateTime'

Date() object

For date and time values.

'boolean'

boolean

For boolean (true/false) values.

'singleSelect'

A value in .valueOptions

Allows selection from predefined options.

'actions'

Not applicable

Used for rendering actions, such as buttons.

For example,

# number column
{"field": "score", "headerName": "Score", "type": "number", "editable": True},
# singleSelect column
{"field": "status", "headerName": "Status", "type": "singleSelect", "valueOptions": ["Active", "Inactive"], "editable": True},

For link, button and checkbox column types, please refer to the later sections. More details, please check the Data Grid

Column is editable

To make a column editable, set the editable property to True in the column definition.

{"field": "score", "headerName": "Score", "dataType": "number", "editable": True},

Initialize the visible columns

By default, all columns are visible. To hide a column, set the hide property to True in the column definition.

{"field": "score", "headerName": "Score", "dataType": "number", "hide": True},

Adding Buttons in Table Columns

You can add interactive buttons to table cells. Define the column with dataType: "button" and optionally customize the button label with buttonLabel.

[4]:

from table_widget import TableWidget
table = TableWidget()

data = pd.DataFrame({
    "name": ["Alice", "Bob", "Charlie"],
    "action": ["", "", ""],  # Placeholder column for button actions
})

columns = [
    {"field": "name", "headerName": "Name", "editable": False},
    {
        "field": "action",
        "headerName": "Action",
        "dataType": "button",
        "buttonLabel": "Click Me",  # Optional custom button label
    },
]

table.from_data(data, columns=columns)
table

[4]:

Adding Checkbox in Table Columns

You can add interactive checkbox to table cells. Define the column with type: "checkbox".

{"field": "include", "headerName": "Include", "type": "checkbox", "editable": True},

Interactive Features

Row Update Observation

The widget allows you to observe updates to rows and react to them. Use it to send the new values to the server and save them into a database or other storage method.

[5]:

def on_row_update(change):
    print("Updated row:", change["new"])

table.observe(on_row_update, "updatedRow")

Dynamic Data Updates

You can dynamically generate and update the data displayed in the table.

[6]:

from table_widget import TableWidget
import random

table = TableWidget()

def generate_data(N):
    return pd.DataFrame({
        "name": [f"Person_{i}" for i in range(N)],
        "score": [random.randint(0, 100) for _ in range(N)],
        "comment": [random.choice(["Excellent", "Good", "Average"]) for _ in range(N)],
    })

# Generate and load new data dynamically
new_data = generate_data(10)
table.from_data(new_data)

Button click Observation

Use it to observe button clicks and react to them.

[7]:


def on_button_click(change):
    print(f"Button clicked for row ID: {change['new']['rowId']} in field: {change['new']['field']}")

table.observe(on_button_click, "clickedButton")

Row selection Observation

Use it to observe row selection and react to it.

[8]:

# select a single row
def on_single_row_select(change):
    print(f"Selected row ID: {change['new']}")

table.observe(on_single_row_select, "selectedRowId")

Multi-Row Selection

The widget supports selecting multiple rows. Use the selectedRows property to get the list of selected rows.

[9]:

from table_widget import TableWidget
import pandas as pd
import ipywidgets as ipw

# Create a table widget
table = TableWidget(style={"height": "500px"}, config={"pagination": True,
                                                       "checkboxSelection": True,})

# Generate data
data = pd.DataFrame({
    "name": ["Alice", "Bob", "Charlie"],
    "score": [85, 90, 78],
    "comment": ["Good", "Excellent", "Average"],
})
columns = [
    {"field": "name", "headerName": "Name", "editable": False},
    {"field": "score", "headerName": "Score", "dataType": "number", "editable": True},
    {"field": "comment", "headerName": "Comment", "editable": True},
]

# Load data into the table
table.from_data(data, columns=columns)

# select a single row
def on_rows_select(change):
    print(f"Selected rows: {change['new']}")

table.observe(on_rows_select, "selectedRows")

table

[9]:

Customization

Style Customization

You can define the table’s appearance using the style parameter.

table.style = {"height": "600px", "width": "100%", "fontSize": "16px"}

Configurable Options

The table supports various configurations via the config parameter:

Config Option

Description

Default Value

checkboxSelection

Enables checkbox selection.

False

pagination

Enables pagination.

True

autoPageSize

Adjusts the page size automatically.

True

pageSize

Set page size manually.

10

disableSelectionOnClick

Disables selection on row click.

False

Example:

table.config = {
    "checkboxSelection": True,
    "pagination": True,
    "disableSelectionOnClick": True,
}

Example Notebook

Below is an example of integrating the table widget into a Jupyter notebook:

[10]:

from table_widget import TableWidget
import pandas as pd
import ipywidgets as ipw

# Create a table widget
table = TableWidget(style={"height": "500px"}, config={"pagination": True})

# Generate data
data = pd.DataFrame({
    "name": ["Alice", "Bob", "Charlie"],
    "score": [85, 90, 78],
    "profile": [
        '<a href="https://example.com/alice" target="_blank">View Profile</a>',
        '<a href="https://example.com/bob" target="_blank">View Profile</a>',
        '<a href="https://example.com/charlie" target="_blank">View Profile</a>',
    ],
    "comment": ["Good", "Excellent", "Average"],
    "status": ["Active", "Inactive", "Active"],
})
columns = [
    {"field": "name", "headerName": "Name", "editable": False},
    {"field": "score", "headerName": "Score", "dataType": "number", "editable": True},
    {"field": "profile", "headerName": "Profile", "dataType": "link", "editable": False},
    {"field": "comment", "headerName": "Comment", "editable": True},
    {"field": "status", "headerName": "Status", "type": "singleSelect", "valueOptions": ["Active", "Inactive"], "editable": True},
]

# Load data into the table
table.from_data(data, columns=columns)
table

[10]:

Now you’re ready to start using the Table Widget in your Jupyter notebooks! For any issues or questions, feel free to reach out to the repository or documentation.