Component | Table

Render a table. Tables offer:

• Actions to add interactivity to each row.
• Customizable columns to format data in a variety of ways.
• Built-in search to filter rows.
• Pagination and virtualization to efficiently scale to millions of rows.

Node.js

const companies = [
   { name: "Apple", tier: "Enterprise", headquarters: "Cupertino, CA", arr: 150000 },
    { name: "Asana", tier: "Basic", headquarters: "San Francisco, CA", arr: 12000 },
    /* ... */
    { name: "Notion", tier: "Basic", headquarters: "San Francisco, CA", arr: 8000 }, 
]

ui.table(
    "table-key",
    companies,
    { 
        label: "Companies",
        actions: [{ 
            label: "View Details", 
            onClick: (row) => page.modal(() => ui.json(row), { title: "Company Details" }) 
        }],
        columns: [
            "name",
            { key: "tier", format: "tag" },
            "headquarters",
            { key: "arr", label: "ARR", format: "currency" }
        ]
    }
)

Python

companies = [
    { "name": "Apple", "tier": "Enterprise", "headquarters": "Cupertino, CA", "arr": 150000 },
    { "name": "Asana", "tier": "Basic", "headquarters": "San Francisco, CA", "arr": 12000 },
    # ...
    { "name": "Notion", "tier": "Basic", "headquarters": "San Francisco, CA", "arr": 8000 },
]

ui.table(
    "table-key",
    companies,
    label="Companies",
    actions=[{ 
        "label": "View Details", 
        "on_click": lambda row: page.modal(lambda: ui.json(row), title="Company Details") 
    }],
    columns=[
        "name",
        { "key": "tier", "format": "tag" },
        "headquarters",
        { "key": "arr", "label": "ARR", "format": "currency" }
    ]
)

node

By default, each row in the table will render with a checkbox. This can be disabled by passing the allowSelect property as false, which will render the table as a display only component.

python

By default, each row in the table will render with a checkbox. This can be disabled by passing the allow_select parameter as False, which will render the table as a display only component.

Learn more about working with inputs.

Row Actions

Actions are a powerful construct that allows you to add row-level interactivity to your table. Tables can have an unlimited number of actions, rendered either as buttons or nested inside a dropdown menu.

Actions are often used as a foundation to create robust multipage apps.

Each action's callback will receive the row as an argument.

Node.js

ui.table("table-key",
<list-of-users>,
{ 
    actions: [
        { label: "Edit", onClick: (row) => doSomething(row) },
        { label: "Delete", onClick: (row) => doSomething(row) },
        // The optional surface field will render the action as a button instead of inside a dropdown (or vice-versa if false).
        { label: "View", onClick: (row, idx) => doSomething(row, idx), surface: true }
    ]
    allowSelect: false
})

Python

ui.table(
    "table-key",
    <list-of-users>,
    actions=[
        { "label": "Edit", "on_click": lambda row: do_something(row) },
        { "label": "Delete", "on_click": lambda row: do_something(row) },
        # The optional surface field will render the action as a button instead of inside a dropdown (or vice-versa if false).
        { "label": "View", "on_click": lambda row, idx: do_something(row, idx), "surface": True }
    ]
    allow_select=False
)

Action object properties

Node.js

label

required string

The user-facing label to display for the action.

Python

label

required str

The user-facing label to display for the action.

---

Node.js

onClick

required (row: TableRow, idx: number) => void

Callback to execute when the action is clicked. The row and index will be passed as arguments.

Python

on_click

required Callable[[TableRow, int], None]

Callback to execute when the action is clicked. The row and index will be passed as arguments.

---

Node.js

surface

optional boolean

Set to true render the action as a button. Set to false to render the action inside a dropdown.

By default, if the table has only one action, it will render as a button. If there are multiple actions, they'll render inside a dropdown.

Python

surface

optional bool

Set to True render the action as a button. Set to False to render the action inside a dropdown.

By default, if the table has only one action, it will render as a button. If there are multiple actions, they'll render inside a dropdown.

---

Columns

By default, Compose infers the table columns and how to render them. This can be overriden by passing the columns property.

Basic Usage

You can pass a list of key strings, which Compose uses to map to the data. This allows you to control which columns are rendered, and in what order, while still leveraging Compose to infer the label and data type.

Node.js

const users = [
    { name: "John", age: 30, createdAt: new Date("2021-01-01"), isActive: true },
    { name: "Jane", age: 25, createdAt: new Date("2021-01-02"), isActive: false },
]

ui.table("table-key", users, { columns: ["name", "age", "isActive"] })

Python

users = [
    {"name": "John", "age": 30, "created_at": datetime(2021, 1, 1), "is_active": True},
    {"name": "Jane", "age": 25, "created_at": datetime(2021, 1, 2), "is_active": False},
]

ui.table("table-key", users, columns=["name", "age", "is_active"])

Advanced Usage

Instead of strings, you can also pass objects that allows you to more granularly control each column. Each column object must have a key field to map to the data.

You can also include optional fields like label, width, and format to override Compose's attempt to infer them.

Node.js

const users = [
    { name: "John", age: 30, createdAt: new Date("2021-01-01"), isActive: true },
    { name: "Jane", age: 25, createdAt: new Date("2021-01-02"), isActive: false },
]

ui.table("table-key", users, {
    columns: [
        { key: "name", width: "150px" },
        "age",
        { key: "createdAt", format: "date" },
        { key: "isActive", label: "Status", format: "boolean" }
    ]
})

Python

users = [
    {"name": "John", "age": 30, "created_at": datetime(2021, 1, 1), "is_active": True},
    {"name": "Jane", "age": 25, "created_at": datetime(2021, 1, 2), "is_active": False},
]

ui.table(
    "table-key",
    users,
    columns=[
        {"key": "name", "width": "150px"},
        "age",
        {"key": "created_at", "format": "date"},
        {"key": "is_active", "label": "Status", "format": "boolean"}
    ]
)

Column object properties

Node.js

key

required string

Specify which property of the data object should be displayed in that column.

Python

key

required str

Specify which property of the data object should be displayed in that column.

---

Node.js

label

optional string

Specify a custom label for the column. If not provided, the label will be inferred from the key

Python

label

optional str

Specify a custom label for the column. If not provided, the label will be inferred from the key

---

Node.js

width

optional string

Specify a custom width for the column (e.g. "150px" or "3rem"). If not provided, the width will be inferred from the content.

Python

width

optional str

Specify a custom width for the column (e.g. "150px" or "3rem"). If not provided, the width will be inferred from the content.

---

Node.js

format

optional string literal

The data type of the column. Specifying this allows Compose to render the column in a more user-friendly format, and sort and filter correctly. If not provided, the format will be inferred from the data.

Options:

• "date": Render a date in a human-friendly format (e.g. Oct 10, 2000). Expects a Date object or ISO string.
• "datetime": Render a datetime in a human-friendly format (e.g. Oct 10, 2000, 11:14 AM). Expects a Date object or ISO string.
• "number": Render a number in a human-friendly format (e.g. 1,234).
• "currency": Render a number in a currency format (e.g. $1,234.56).
• "boolean": Render a boolean in a human-friendly format (e.g. `✅` or `❌`). Will perform a truthiness check on non-boolean values.
• "tag": Render values (or lists of values) as colored pills. Useful for enum-type data. You can pass a tagColors property to specify the colors of the tags. If not provided, Compose will randomly assign colors to each value.
• "string": Stringify the value and render as is. Use when you don't want any special formatting.

Python

format

optional Literal

The data type of the column. Specifying this allows Compose to render the column in a more user-friendly format, and sort and filter correctly. If not provided, the format will be inferred from the data.

Options:

• "date": Render a date in a human-friendly format (e.g. Oct 10, 2000). Expects a datetime object or ISO string.
• "datetime": Render a datetime in a human-friendly format (e.g. Oct 10, 2000, 11:14 AM). Expects a datetime object or ISO string.
• "number": Render a number in a human-friendly format (e.g. 1,234).
• "currency": Render a number in a currency format (e.g. $1,234.56).
• "boolean": Render a boolean in a human-friendly format (e.g. `✅` or `❌`). Will perform a truthiness check on non-boolean values.
• "tag": Render values (or lists of values) as colored pills. Useful for enum-type data. You can pass a tag_colors property to specify the colors of the tags. If not provided, Compose will randomly assign colors to each value.
• "string": Stringify the value and render as is. Use when you don't want any special formatting.

---

Node.js

tagColors

optional Record<string, string | string[]>SDK v0.23.0+

Map tag colors to column values when using format: "tag". If this property is not provided, Compose will randomly assign colors to each value.

Colors can be mapped to single values or arrays of values. If a value isn't mapped to a color, it will use the _default color if specified, or be automatically assigned a color.

Available colors: red, orange, yellow, green, blue, purple, pink, gray, brown.

Example:

{
  key: "status",
  format: "tag",
  tagColors: {
    purple: ["todo", "backlog"],
    orange: "in_progress",
    green: "done",
    _default: "gray" // Render any unmapped values as gray
  }
}

Compose tags support string, number, and boolean values, or lists of these values. Any other value will be rendered as plain text.

Python

tag_colors

optional dict[str, str | list[str]]SDK v0.23.0+

Map tag colors to column values when using format: "tag". If this property is not provided, Compose will randomly assign colors to each value.

Colors can be mapped to single values or arrays of values. If a value isn't mapped to a color, it will use the _default color if specified, or be automatically assigned a color.

Available colors: red, orange, yellow, green, blue, purple, pink, gray, brown.

Example:

{
  "key": "status",
  "format": "tag",
  "tag_colors": {
    "purple": ["todo", "backlog"],
    "orange": "in_progress",
    "green": "done",
    "_default": "gray" # Render any unmapped values as gray
  }
}

Compose tags support str, int, float, and bool values, or lists of these values. Any other value will be rendered as plain text.

---

Pagination

Introduced in SDK v0.24.0.

Automatic Pagination

Tables with more than 5000 rows are automatically paginated without any additional configuration on your end, enabling Compose to remain performant at scale.

An important caveat is that auto-pagination disables client-side search since the browser only has a paginated subset of the data. You can re-enable search by manually paginating the table.

Manual Pagination

For very large datasets, you can manually paginate tables by passing a getter function to the data parameter. Manual pagination enables you to:

• fetch data from your data store as needed, instead of having to load everything into memory at once.
• manage search using your own custom logic.
• scale endlessly (millions of rows) without performance degradation.

Node.js

import { TablePageChangeParams, TablePageChangeResponse } from "@composehq/sdk"

async function onPageChange(params: TablePageChangeParams): TablePageChangeResponse {
    const { offset, pageSize, searchQuery, prevTotalRecords, prevSearchQuery } = params;

    // Only refetch total records on initial load and when the search query changes.
    const refetchTotal =
        prevTotalRecords === null || prevSearchQuery !== searchQuery;

    const totalRecords = refetchTotal
        ? await postgres.countUsers(searchQuery)
        : prevTotalRecords;

    const pageOfUsers = await postgres.getUsers(offset, pageSize, searchQuery);

    return {
        data: pageOfUsers,
        totalRecords,
    };
}

page.add(() => ui.table("users-table", onPageChange))

Python

import compose_sdk as c

def on_page_change(args: c.TablePageChangeArgs) -> c.TablePageChangeResponse:
    # Unpack arguments
    offset = args["offset"]
    page_size = args["page_size"]
    search_query = args["search_query"]
    prev_total_records = args["prev_total_records"]
    prev_search_query = args["prev_search_query"]

    # Only refetch total records on initial load and when the search query changes
    refetch_total = prev_total_records is None or prev_search_query != search_query

    total_records = (
        postgres.count_users(search_query) if refetch_total else prev_total_records
    )

    page_of_users = postgres.get_users(offset, page_size, search_query)

    return {"data": page_of_users, "total_records": total_records}

page.add(lambda: ui.table("users-table", on_page_change))

Type definitions:

Node.js

// Passed to the onPageChange callback as a single object.
interface TablePageChangeParams {
    // The number of rows to skip.
    offset: number;
    // The number of rows to return. You can return less than this if there
    // aren't enough rows to fill the page (e.g. the last page).
    pageSize: number;
    // The search query to filter the rows by. Will be null if no search
    // is being performed.
    searchQuery: string | null;
    // The previous total number of records. This is provided so that you
    // only recalculate the total record count when needed.
    prevTotalRecords: number | null;
    // The previous search query. This is provided so that you only
    // recalculate the total record count when needed.
    prevSearchQuery: string | null;
}

// Expected return type of the onPageChange callback.
interface TablePageChangeResponse {
    // The data for the current page. Should be an array of objects.
    data: TableData;
    // The total number of records. This is used to calculate the number
    // of pages.
    totalRecords: number;
}

Python

# Passed to the on_page_change callback as a single positional argument.
class TablePageChangeArgs(TypedDict):
    # The number of rows to skip.
    offset: int
    # The number of rows to return. You can return less than this if there
    # aren't enough rows to fill the page (e.g. the last page).
    page_size: int
    # The search query to filter the rows by. Will be null if no search
    # is being performed.
    search_query: str | None
    # The previous total number of records. This is provided so that you
    # only recalculate the total record count when needed.
    prev_total_records: int | None
    # The previous search query. This is provided so that you only
    # recalculate the total record count when needed.
    prev_search_query: str | None

# The expected return type of the on_page_change callback.
class TablePageChangeResponse(TypedDict):
    # The data for the current page. Should be a list of dictionaries.
    data: TableData
    # The total number of records. This is used to calculate the number
    # of pages.
    total_records: int

note

If you're not yet ready to handle search, you can disable it by passing the searchable: false property to the table.

Row Selections

Node.js

Compose disables row selections by default for paginated tables. Due to constraints introduced by server-side pagination, it's not possible for Compose to pass a list of table rows to callbacks (e.g. onChange or onSubmit) when the user selects rows.

You can re-enable row selections by passing a selectionReturnType: "index" property to the table. When this is enabled, Compose will pass a list of row indices to any callbacks instead of the rows themselves.

Python

Compose disables row selections by default for paginated tables. Due to constraints introduced by server-side pagination, it's not possible for Compose to pass a list of table rows to callbacks (e.g. on_change or on_submit) when the user selects rows.

You can re-enable row selections by passing a selection_return_type: "index" property to the table. When this is enabled, Compose will pass a list of row indices to any callbacks instead of the rows themselves.

Node.js

ui.table(
    "users-table",
    onPageChange,
    {
        selectionReturnType: "index",
        onChange: (selectedRows) => {
            console.log(selectedRows) // [0, 1, 2, ...]
        }
    }
)

Python

ui.table(
    "users-table",
    on_page_change,
    selection_return_type="index",
    on_change=lambda selected_rows: print(selected_rows) # [0, 1, 2, ...]
)

API reference

Function signature

Node.js

type TableRow = {
    [key: string]: string | number | boolean | Date | null | undefined | object
}

ui.table<T extends TableRow>(
    id: string,
    data: T[] | TablePageChangeCallback<T>,
    properties?: Partial<{
        allowSelect: boolean,
        label: string,
        description: string,
        required: boolean 
        initialSelectedRows: number[],
        validate: (values: T[]) => string | void,
        onChange: (values: T[]) => void,
        columns: TableColumn[],
        actions: TableAction<T>[],
        minSelections: number,
        maxSelections: number,
        selectionReturnType: "full" | "index",
        searchable: boolean,
        style: Style,
    }>
)

Python

TableDataRow = Dict[str, Any]
TableData = List[TableDataRow]

ui.table(
    id: str,
    data: TableData | TablePageChangeCallback,
    *,
    allow_select: bool = True,
    label: str | None = None,
    description: str | None = None,
    required: bool = True,
    initial_selected_rows: list[int] | None = None,
    validate: Callable[[TableData], str | None] | None = None,
    on_change: Callable[[TableData], None] | None = None,
    columns: TableColumns | None = None,
    actions: list[TableAction] | None = None,
    min_selections: int = 0,
    max_selections: int = 1000000000,
    selection_return_type: Literal["full", "index"] = "full",
    searchable: bool = True,
    style: Style | None = None,
)

Parameters

Node.js

id

required string

A unique identifier for the component. This is necessary so that Compose can properly pass user actions back to the component.

Python

id

required str

A unique identifier for the component. This is necessary so that Compose can properly pass user actions back to the component.

---

Node.js

data

required TableRow[] | TablePageChangeCallback

The data to be displayed in the table. Each item in the array represents a row in the table, and should be an object where the keys correspond to column names and the values are the cell contents.

Compose supports most data types including strings, numbers, booleans, dates, and objects.

For larger datasets, you can paginate the table server-side by passing a function that returns one page of data at a time. See the pagination section for more details.

Python

data

required TableData | TablePageChangeCallback

The data to be displayed in the table. Each item in the list represents a row in the table, and should be a dictionary where the keys correspond to column names and the values are the cell contents.

Compose supports most data types including strings, numbers, booleans, dates, and objects.

For larger datasets, you can paginate the table server-side by passing a function that returns one page of data at a time. See the pagination section for more details.

---

Node.js

properties.allowSelect

optional boolean

Whether to show the selections column. Defaults to true.

Python

allow_select

optional bool

Whether to show the selections column. Defaults to True.

---

Node.js

properties.label

optional string

The label to display above the table. If not provided, the label will be inferred from the id.

Python

label

optional str

The label to display above the table. If not provided, the label will be inferred from the id.

---

Node.js

properties.description

optional string

A description to display between the label and table.

Python

description

optional str

A description to display between the label and table.

---

Node.js

properties.required

optional boolean

Validate that the table has at least one row selected before submitting the form it's part of or calling it's onChange hook. Defaults to true.

Python

required

optional bool

Validate that the table has at least one row selected before submitting the form it's part of or calling it's on_change hook. Defaults to True.

---

Node.js

properties.initialSelectedRows

optional number[]

A list of row indices to pre-select when the table is first rendered. Defaults to [] (empty list).

Python

initial_selected_rows

optional list[int]

A list of row indices to pre-select when the table is first rendered. Defaults to [] (empty list).

---

Node.js

properties.validate

optional (selectedRows: TableRow[]) => string | void

Validate the selected rows before submitting. If the function returns a string, it will be displayed as an error message.

Python

validate

optional Callable[[TableData], str | None]

Validate the selected rows before submitting. If the function returns a string, it will be displayed as an error message.

---

Node.js

properties.onChange

optional (selectedRows: TableRow[]) => void

A callback function that is called when the table selection(s) change. The callback is passed the list of currently selected rows.

Python

on_change

optional Callable[[TableData], None]

A callback function that is called when the table selection(s) change. The callback is passed the list of currently selected rows.

---

Node.js

properties.columns

optional TableColumn[]

Control how columns are rendered in the table. If not provided, Compose will default to using the keys from the first row of data, then do it's best to infer human readable column names, data types, etc. See the columns section for more details.

Python

columns

optional list[TableColumn]

Control how columns are rendered in the table. If not provided, Compose will default to using the keys from the first row of data, then do it's best to infer human readable column names, data types, etc. See the columns section for more details.

---

Node.js

properties.actions

optional TableAction[]

Add row-level action buttons that execute custom functions when clicked. See the row actions section for more details.

Python

actions

optional list[TableAction]

Add row-level action buttons that execute custom functions when clicked. See the row actions section for more details.

---

Node.js

properties.minSelections

optional number

Validate that the user has selected at least some number of rows. Defaults to 0.

Python

min_selections

optional int

Validate that the user has selected at least some number of rows. Defaults to 0.

---

Node.js

properties.maxSelections

optional number

Validate that the user has selected at most some number of rows. Defaults to 1000000000.

Python

max_selections

optional int

Validate that the user has selected at most some number of rows. Defaults to 1000000000.

---

Node.js

properties.selectionReturnType

optional string literalSDK v0.24.0+

Options:

• "full": Return the full row data to callback functions when the user selects rows.
• "index": Return the row indices to callback functions when the user selects rows.

By default, this property is set to "full".

Paginated tables only support row selections by index. If you're using a paginated table, you'll need to set this property to "index" to enable row selections. If not, Compose will disable row selections for the paginated table.

Python

selection_return_type

optional LiteralSDK v0.24.0+

Options:

• "full": Return the full row data to callback functions when the user selects rows.
• "index": Return the row indices to callback functions when the user selects rows.

By default, this property is set to "full".

Paginated tables only support row selections by index. If you're using a paginated table, you'll need to set this property to "index" to enable row selections. If not, Compose will disable row selections for the paginated table.

---

Node.js

properties.searchable

optional booleanSDK v0.24.0+

Whether to show the search input. Defaults to true.

The exception is auto-paginated tables (i.e. tables with more than 5000 rows). Client-side search is not possible for these tables, and you'll need to manage search yourself using manual pagination.

Python

searchable

optional boolSDK v0.24.0+

Whether to show the search input. Defaults to True.

The exception is auto-paginated tables (i.e. tables with more than 5000 rows). Client-side search is not possible for these tables, and you'll need to manage search yourself using manual pagination.

---

Node.js

properties.style

optional Style

Directly style the underlying element using CSS. See the styling guide for more details on available style properties.

Python

style

optional Style | None

Directly style the underlying element using CSS. See the styling guide for more details on available style properties.

---