io.display.table
Displays tabular data.
Usage
- TypeScript
- JavaScript
- Python Experimental
await io.display.table("Albums", {
helpText: "Includes the artist and its year of release.",
data: [
{
album: "Exile on Main Street",
artist: "The Rolling Stones",
year: 1972,
},
{
album: "Thriller",
artist: "Michael Jackson",
year: 1982,
},
{
album: "Enter the Wu-Tang (36 Chambers)",
artist: "Wu-Tang Clan",
year: 1993,
},
],
});
await io.display.table("Albums", {
helpText: "Includes the artist and its year of release.",
data: [
{
album: "Exile on Main Street",
artist: "The Rolling Stones",
year: 1972,
},
{
album: "Thriller",
artist: "Michael Jackson",
year: 1982,
},
{
album: "Enter the Wu-Tang (36 Chambers)",
artist: "Wu-Tang Clan",
year: 1993,
},
],
});
await io.display.table(
"Albums",
help_text="Includes the artist and its year of release.",
data=[
{
"album": "Exile on Main Street",
"artist": "The Rolling Stones",
"year": 1972,
},
{
"album": "Thriller",
"artist": "Michael Jackson",
"year": 1982,
},
{
"album": "Enter the Wu-Tang (36 Chambers)",
"artist": "Wu-Tang Clan",
"year": 1993,
},
],
};
Props
- TypeScript
- JavaScript
- Python Experimental
columns
Optional
(string | object)[]
accessorKey
Optional
string
label
Required
string
renderCell
Optional
(row: T) => string | object
renderCell: (row: T) => string | {
// the visible cell label
label?: string | number | boolean | Date;
// an optional underlying value for sorting
value?: string | number | boolean | Date;
// links the cell's contents to an external URL
url?: string;
// links the cell's contents to another action or page
route?: string;
// arbitrary key/value pairs to send to the linked route
params?: Record<string, any>;
// a visible image to be displayed in the cell
// must contain either `url` or `buffer`
image?: {
// a URL to the image
url?: string
// a buffer containing the image contents
buffer?: Buffer
// the image alt tag
alt?: string
// the size of the image
size?: "thumbnail" | "small" | "medium" | "large"
}
}
data
Optional
T[]
defaultPageSize
Optional
number
getData
Optional
(state) => Promise<{ data: T[], totalRecords?: number }>
getData: (
state: {
// the user's search query, may be an empty string
queryTerm?: string,
// the `accessorKey` for the column being sorted
sortColumn?: string,
// the sort direction for the column being sorted
sortDirection?: "asc" | "desc",
// the number of records to skip for the current
// `queryTerm` and sorting, for pagination
offset: number,
// the current page size, should return at least this
// many records if available
pageSize: number
}
}) => Promise<{
// the underlying data records for this table state
data: T[],
// the total number of records available for this queryTerm, if known
totalRecords?: number
}>
helpText
Optional
string
isFilterable
Optional
boolean
isSortable
Optional
boolean
orientation
Optional
'horizontal' | 'vertical'
rowMenuItems
Optional
(row: T) => object[]
rowMenuItems: (row: T) => {
// the visible menu item label
label: string;
// links the menu item to an external URL
url?: string;
// links the menu item to another action or page
route?: string;
// arbitrary key/value pairs to send to the linked route
params?: Record<string, any>;
// disables the menu item
disabled?: boolean
// the style of the item
theme?: 'danger' | undefined
}[]
Returns
null
columns
Optional
(string | object)[]
accessorKey
Optional
string
label
Required
string
renderCell
Optional
(row: T) => string | object
renderCell: (row: T) => string | {
// the visible cell label
label?: string | number | boolean | Date;
// an optional underlying value for sorting
value?: string | number | boolean | Date;
// links the cell's contents to an external URL
url?: string;
// links the cell's contents to another action or page
route?: string;
// arbitrary key/value pairs to send to the linked route
params?: Record<string, any>;
// a visible image to be displayed in the cell
// must contain either `url` or `buffer`
image?: {
// a URL to the image
url?: string
// a buffer containing the image contents
buffer?: Buffer
// the image alt tag
alt?: string
// the size of the image
size?: "thumbnail" | "small" | "medium" | "large"
}
}
data
Optional
T[]
defaultPageSize
Optional
number
getData
Optional
(state) => Promise<{ data: T[], totalRecords?: number }>
getData: (
state: {
// the user's search query, may be an empty string
queryTerm?: string,
// the `accessorKey` for the column being sorted
sortColumn?: string,
// the sort direction for the column being sorted
sortDirection?: "asc" | "desc",
// the number of records to skip for the current
// `queryTerm` and sorting, for pagination
offset: number,
// the current page size, should return at least this
// many records if available
pageSize: number
}
}) => Promise<{
// the underlying data records for this table state
data: T[],
// the total number of records available for this queryTerm, if known
totalRecords?: number
}>
helpText
Optional
string
isFilterable
Optional
boolean
isSortable
Optional
boolean
orientation
Optional
'horizontal' | 'vertical'
rowMenuItems
Optional
(row: T) => object[]
rowMenuItems: (row: T) => {
// the visible menu item label
label: string;
// links the menu item to an external URL
url?: string;
// links the menu item to another action or page
route?: string;
// arbitrary key/value pairs to send to the linked route
params?: Record<string, any>;
// disables the menu item
disabled?: boolean
// the style of the item
theme?: 'danger' | undefined
}[]
Returns
null
columns
Optional
Iterable[TableColumn | str]
data
Optional
Iterable[T]
default_page_size
Optional
int
get_data
Optional
(TableDataFetcherState) -> Awaitable[Iterable[TableRow] | tuple[Iterable[TableRow], int]]
help_text
Optional
str
is_filterable
Optional
bool
is_sortable
Optional
bool
orientation
Optional
Literal["horizontal" | "vertical"]
row_menu_items
Optional
(TableRow) -> MenuItem
Returns
None
Examples
Customizing output
The default behavior shown above is to display all of the fields in each
record. To customize the display of records, a columns
property can be
provided. The columns
property can contain an array of data
property
names, and only those columns will be displayed in the table.
- TypeScript
- JavaScript
- Python Experimental
await io.display.table("Users", {
data: [
{
email: "carsta.rocha@example.com",
phone_number: "(60) 1416-4953",
birthdate: "1993-08-04",
first_name: "Carsta",
last_name: "Rocha",
image: "https://example.com/photos/21351234.jpg",
website_url: "https://example.com",
},
{
email: "irene.morales@example.org",
phone_number: "625-790-958",
birthdate: "1982-04-28",
first_name: "Irene",
last_name: "Morales",
image: "https://example.com/photos/8321527.jpg",
website_url: "https://example.org",
},
],
columns: ["first_name", "last_name", "email"],
});
await io.display.table("Users", {
data: [
{
email: "carsta.rocha@example.com",
phone_number: "(60) 1416-4953",
birthdate: "1993-08-04",
first_name: "Carsta",
last_name: "Rocha",
image: "https://example.com/photos/21351234.jpg",
website_url: "https://example.com",
},
{
email: "irene.morales@example.org",
phone_number: "625-790-958",
birthdate: "1982-04-28",
first_name: "Irene",
last_name: "Morales",
image: "https://example.com/photos/8321527.jpg",
website_url: "https://example.org",
},
],
columns: ["first_name", "last_name", "email"],
});
await io.display.table(
"Users",
data=[
{
"email": "carsta.rocha@example.com",
"phone_number": "(60) 1416-4953",
"birthdate": "1993-08-04",
"first_name": "Carsta",
"last_name": "Rocha",
"image": "https://example.com/photos/21351234.jpg",
"website_url": "https://example.com",
},
{
"email": "irene.morales@example.org",
"phone_number": "625-790-958",
"birthdate": "1982-04-28",
"first_name": "Irene",
"last_name": "Morales",
"image": "https://example.com/photos/8321527.jpg",
"website_url": "https://example.org",
},
],
columns=["first_name", "last_name", "email"],
)
The columns
array can also contain definition objects, with a label
property and either an accessorKey
string or a renderCell
callback that returns an object with optional label
, value
, url
, action
string properties, and optional params
and image
object properties.
- TypeScript
- JavaScript
- Python Experimental
await io.display.table("Users", {
data: [
{
email: "carsta.rocha@example.com",
phone_number: "(60) 1416-4953",
birthdate: "1993-08-04",
first_name: "Carsta",
last_name: "Rocha",
image: "https://example.com/photos/21351234.jpg",
website_url: "https://example.com",
},
{
email: "irene.morales@example.org",
phone_number: "625-790-958",
birthdate: "1982-04-28",
first_name: "Irene",
last_name: "Morales",
image: "https://example.com/photos/8321527.jpg",
website_url: "https://example.org",
},
],
columns: [
{
label: "Name",
renderCell: row => `${row.first_name} ${row.last_name}`,
},
{
label: "Phone number",
accessorKey: "phone_number",
},
{
label: "Photo",
renderCell: row => ({
image: {
url: row.image,
alt: `${row.first_name} ${row.last_name} profile photo`,
size: "small",
},
}),
},
{
label: "Birth date",
renderCell: row => {
const [y, m, d] = row.birthdate.split("-").map(s => Number(s));
const birthDate = new Date(y, m - 1, d);
return {
label: birthDate.toLocaleDateString(),
value: birthDate,
};
},
},
{
label: "Website",
renderCell: row => ({
label: row.website_url,
url: row.website_url,
}),
},
{
label: "Edit action",
renderCell: row => ({
label: "Edit user",
action: "edit_user",
params: {
email: row.email,
},
}),
},
],
});
await io.display.table("Users", {
data: [
{
email: "carsta.rocha@example.com",
phone_number: "(60) 1416-4953",
birthdate: "1993-08-04",
first_name: "Carsta",
last_name: "Rocha",
image: "https://example.com/photos/21351234.jpg",
website_url: "https://example.com",
},
{
email: "irene.morales@example.org",
phone_number: "625-790-958",
birthdate: "1982-04-28",
first_name: "Irene",
last_name: "Morales",
image: "https://example.com/photos/8321527.jpg",
website_url: "https://example.org",
},
],
columns: [
{
label: "Name",
renderCell: row => `${row.first_name} ${row.last_name}`,
},
{
label: "Phone number",
accessorKey: "phone_number",
},
{
label: "Photo",
renderCell: row => ({
image: {
url: row.image,
alt: `${row.first_name} ${row.last_name} profile photo`,
size: "small",
},
}),
},
{
label: "Birth date",
renderCell: row => {
const [y, m, d] = row.birthdate.split("-").map(s => Number(s));
const birthDate = new Date(y, m - 1, d);
return {
label: birthDate.toLocaleDateString(),
value: birthDate,
};
},
},
{
label: "Website",
renderCell: row => ({
label: row.website_url,
url: row.website_url,
}),
},
{
label: "Edit action",
renderCell: row => ({
label: "Edit user",
action: "edit_user",
params: {
email: row.email,
},
}),
},
],
});
await io.display.table(
"Users",
data=[
{
"email": "carsta.rocha@example.com",
"phone_number": "(60) 1416-4953",
"birthdate": "1993-08-04",
"first_name": "Carsta",
"last_name": "Rocha",
"image": "https://example.com/photos/21351234.jpg",
"website_url": "https://example.com",
},
{
"email": "irene.morales@example.org",
"phone_number": "625-790-958",
"birthdate": "1982-04-28",
"first_name": "Irene",
"last_name": "Morales",
"image": "https://example.com/photos/8321527.jpg",
"website_url": "https://example.org",
},
],
columns=[
{
"label": "Name",
"renderCell": lambda row: f"{row['first_name']} {row['last_name']}",
},
{
"label": "Phone number",
"accessorKey": "phone_number",
},
{
"label": "Photo",
"renderCell": lambda row: {
"image": {
"url": row.image,
"alt": f"{row['first_name']} {row['last_name']} profile photo",
"size": "small",
},
},
},
{
"label": "Website",
"renderCell": lambda row: {
"label": row['website_url'],
"url": row['website_url'],
},
},
{
"label": "Edit action",
"renderCell": lambda row: {
"label": "Edit user",
"action": "edit_user",
"params": {
"email": row['email'],
},
},
},
],
)
If the renderCell
callback returns an action
property, a link will be
generated to the action with that slug. A params
object can also be defined,
this object will be passed to the action's ctx.params
context value.
tip
The two forms shown above can be combined within a single columns
definition.
Adding menus
Beginning with SDK v0.25.0, each row can be given a dropdown menu using the rowMenuItems
property, a function that provides the current row as the only argument and returns an array of menu items. Menu items are typically links to other actions.
- TypeScript
- JavaScript
- Python Experimental
await io.display.table("Albums", {
data: albums,
columns: ["album", "artist", "year"],
rowMenuItems: row => [
{
label: "Edit metadata",
action: "edit_album",
params: { id: row.id },
},
{
label: "Listen on Spotify",
// external URLs automatically open in a new tab.
url: `https://open.spotify.com/album/${row.spotifyId}`,
},
],
});
await io.display.table("Albums", {
data: albums,
columns: ["album", "artist", "year"],
rowMenuItems: row => [
{
label: "Edit metadata",
action: "edit_album",
params: { id: row.id },
},
{
label: "Listen on Spotify",
// external URLs automatically open in a new tab.
url: `https://open.spotify.com/album/${row.spotifyId}`,
},
],
});
await io.display.table(
"Albums",
data=albums,
columns=["album", "artist", "year"],
row_menu_items=lambda row: [
{
"label": "Edit metadata",
"action": "edit_album",
"params": { id: row['id'] },
},
{
"label": "Listen on Spotify",
# external URLs automatically open in a new tab.
"url": f"https://open.spotify.com/album/{row['spotifyId']}",
},
],
)
Asynchronous data
tip
Best for situations like:
- Large data sets of thousands of records
- Fetching additional data from external APIs like Stripe
Beginning with SDK v0.31.0, data can be fetched asynchronously depending on user input like searching and page navigation. This allows advanced use cases like displaying large or external data sets without needing to fetch the entire set of records up front.
Fetching data asynchronously prevents many user experience enhancements
like caching table data, client-side searching and pagination, and
requires more code to account for search, sorting, and pagination.
When in doubt, start with the synchronous data
property and use this
when the situation requires it.
info
Columns in async data tables are only available for sorting if the column
is statically defined with an accessorKey
property or via string shorthand.
- TypeScript
- JavaScript
- Python Experimental
await io.display.table("Purchases", {
getData: async ({
queryTerm,
sortColumn,
sortDirection,
offset,
pageSize,
}) => {
const where = {
OR: [
{
buyer: {
name: {
search: queryTerm,
},
},
},
{
product: {
name: {
search: queryTerm,
},
},
},
],
};
let orderBy;
if (sortColumn && sortDirection) {
orderBy = {
[sortColumn]: sortDirection,
};
}
const data = await db.purchases.find({
where,
skip: offset,
limit: pageSize,
orderBy,
});
const totalRecords = await db.purchases.count({
where,
});
return {
data,
totalRecords,
};
},
columns: [
{
label: "Buyer",
renderCell: row => row.buyer.name,
},
{
label: "Product",
renderCell: row => row.product.name,
},
{
label: "Amount",
accessorKey: "totalPrice",
},
],
});
await io.display.table("Purchases", {
getData: async ({
queryTerm,
sortColumn,
sortDirection,
offset,
pageSize,
}) => {
const where = {
OR: [
{
buyer: {
name: {
search: queryTerm,
},
},
},
{
product: {
name: {
search: queryTerm,
},
},
},
],
};
let orderBy;
if (sortColumn && sortDirection) {
orderBy = {
[sortColumn]: sortDirection,
};
}
const data = await db.purchases.find({
where,
skip: offset,
limit: pageSize,
orderBy,
});
const totalRecords = await db.purchases.count({
where,
});
return {
data,
totalRecords,
};
},
columns: [
{
label: "Buyer",
renderCell: row => row.buyer.name,
},
{
label: "Product",
renderCell: row => row.product.name,
},
{
label: "Amount",
accessorKey: "totalPrice",
},
],
});
from interval_sdk import GridDataFetcherState
async def get_data(state: TableDataFetcherState):
where = { "OR": [
{ "buyer": { "name": { "search": state.query_term } } },
{ "product": { "name": { "search": state.query_term } } },
]}
total_records = mydb.purchases.count(
where=where,
)
order_by = None
if state.sort_column and state.sort_direction:
order_by = { state.sort_column: state.sort_direction }
results = mydb.purchases.find(
where=where,
skip=state.offset,
limit=state.page_size,
order_by=order_by,
)
return (results, total_records)
await io.display.table("Purchases",
get_data=get_data,
columns=[
{
"label": "Buyer",
"renderCell": lambda row: row["buyer"]["name"],
},
{
"label": "Product",
"renderCell": lambda row: row["product"]["name"],
},
{
"label": "Amount",
"accessorKey": "totalPrice",
},
],
)
danger
Be sure to safely sanitize, escape, or prepare all values before passing them to any database queries.