Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs(table): lead with rich renderCell examples and add composition hints (#405)

Cindy Zhangd9095f7d181c
diff --git a/packages/core/src/Table/README.md b/packages/core/src/Table/README.md
index 3cbb3f931d..9d94ecb04e 100644
--- a/packages/core/src/Table/README.md
+++ b/packages/core/src/Table/README.md
@@ -1,6 +1,7 @@
# Table
-Table components for the XDS design system.
+Data-driven table with rich cell content via `renderCell`. Compose cells with
+XDSBadge, XDSStatusDot, XDSText, XDSAvatar, and layout primitives.
<!-- SYNC: When files in this directory change, update this document. -->
@@ -47,14 +48,52 @@ Table components for the XDS design system.
### XDSTable
-Styled, data-driven table with density, dividers, hover, and plugin support.
+Styled, data-driven table. Use `renderCell` on columns for rich cell content —
+compose with XDSBadge, XDSStatusDot, XDSText, XDSAvatar, and layout primitives.
```tsx
<XDSTable
data={users}
columns={[
- {key: 'name', header: 'Name'},
- {key: 'email', header: 'Email', width: proportional(2)},
+ {
+ key: 'name',
+ header: 'Name',
+ renderCell: user => (
+ <XDSHStack gap="space2" align="center">
+ <XDSAvatar name={user.name} size="small" />
+ <XDSVStack gap="space1">
+ <XDSText type="body" weight="semibold">
+ {user.name}
+ </XDSText>
+ <XDSText type="supporting" color="secondary">
+ {user.email}
+ </XDSText>
+ </XDSVStack>
+ </XDSHStack>
+ ),
+ },
+ {
+ key: 'status',
+ header: 'Status',
+ width: pixel(140),
+ renderCell: user => (
+ <XDSHStack gap="space2" align="center">
+ <XDSStatusDot status={user.isActive ? 'positive' : 'negative'} />
+ <XDSBadge variant={user.isActive ? 'success' : 'error'}>
+ {user.isActive ? 'Active' : 'Inactive'}
+ </XDSBadge>
+ </XDSHStack>
+ ),
+ },
+ {
+ key: 'role',
+ header: 'Role',
+ renderCell: user => (
+ <XDSText type="label" color="secondary">
+ {user.role}
+ </XDSText>
+ ),
+ },
]}
density="balanced"
dividers="rows"
@@ -62,17 +101,17 @@ Styled, data-driven table with density, dividers, hover, and plugin support.
/>
```
-| Prop | Type | Default | Description |
-| ----------- | --------------------------------- | ------------ | ------------------------------------ |
-| `data` | `T[]` | — | Array of data items |
-| `columns` | `XDSTableColumn<T>[]` | — | Column definitions (auto-generated if omitted) |
-| `idKey` | `string \| (item: T) => string` | — | Row key for React reconciliation |
-| `density` | `'compact' \| 'balanced' \| 'spacious'` | `'balanced'` | Row density |
-| `dividers` | `XDSTableDividers` | `'rows'` | Divider style |
-| `isStriped` | `boolean` | `false` | Striped even rows |
-| `hasHover` | `boolean` | `false` | Hover highlight on rows |
-| `plugins` | `Record<string, TablePlugin<T>>` | — | Named plugins to extend behavior |
-| `children` | `ReactNode` | — | Children mode (manual rows) |
+| Prop | Type | Default | Description |
+| ----------- | --------------------------------------- | ------------ | -------------------------------------------------------------- |
+| `data` | `T[]` | — | Array of data items |
+| `columns` | `XDSTableColumn<T>[]` | — | Column definitions with optional `renderCell` for rich content |
+| `idKey` | `string \| (item: T) => string` | — | Row key for React reconciliation |
+| `density` | `'compact' \| 'balanced' \| 'spacious'` | `'balanced'` | Row density |
+| `dividers` | `XDSTableDividers` | `'rows'` | Divider style |
+| `isStriped` | `boolean` | `false` | Striped even rows |
+| `hasHover` | `boolean` | `false` | Hover highlight on rows |
+| `plugins` | `Record<string, TablePlugin<T>>` | — | Named plugins to extend behavior |
+| `children` | `ReactNode` | — | Children mode (manual rows) |
### XDSBaseTable
@@ -83,19 +122,19 @@ Unstyled table with colgroup, plugin pipeline, and components prop for custom re
data={items}
columns={columns}
plugins={[myPlugin]}
- components={{ Row: XDSTableRow, Cell: XDSTableCell }}
+ components={{Row: XDSTableRow, Cell: XDSTableCell}}
/>
```
-| Prop | Type | Default | Description |
-| ------------ | -------------------------- | ------- | ----------------------------------------- |
-| `data` | `T[]` | — | Array of data items |
-| `columns` | `XDSTableColumn<T>[]` | — | Column definitions |
-| `idKey` | `string \| (item: T) => string` | — | Row key for React reconciliation |
-| `plugins` | `TablePlugin<T>[]` | — | Ordered plugins for transform pipeline |
-| `components` | `{Row?, Cell?, HeaderCell?}` | — | Component overrides for table elements |
-| `children` | `ReactNode` | — | Children mode |
-| `tableProps` | `HTMLAttributes` | — | Additional attrs for `<table>` element |
+| Prop | Type | Default | Description |
+| ------------ | ------------------------------- | ------- | -------------------------------------- |
+| `data` | `T[]` | — | Array of data items |
+| `columns` | `XDSTableColumn<T>[]` | — | Column definitions |
+| `idKey` | `string \| (item: T) => string` | — | Row key for React reconciliation |
+| `plugins` | `TablePlugin<T>[]` | — | Ordered plugins for transform pipeline |
+| `components` | `{Row?, Cell?, HeaderCell?}` | — | Component overrides for table elements |
+| `children` | `ReactNode` | — | Children mode |
+| `tableProps` | `HTMLAttributes` | — | Additional attrs for `<table>` element |
### XDSTableRow
@@ -115,15 +154,22 @@ Unstyled table with colgroup, plugin pipeline, and components prop for custom re
### XDSTableCell
-`<td>` wrapper with context-aware styling and xstyle support.
+`<td>` wrapper with context-aware styling and xstyle support. Accepts any ReactNode
+as children — compose rich content with XDS components like XDSBadge, XDSStatusDot,
+XDSText, XDSAvatar, and layout primitives.
```tsx
-<XDSTableCell>Cell content</XDSTableCell>
+<XDSTableCell>
+ <XDSHStack gap="space2" align="center">
+ <XDSStatusDot status="positive" />
+ <XDSText weight="semibold">Active</XDSText>
+ </XDSHStack>
+</XDSTableCell>
```
-| Prop | Type | Default | Description |
-| ---------- | -------------------------------- | ------- | --------------- |
-| `children` | `ReactNode` | — | Cell content |
+| Prop | Type | Default | Description |
+| ---------- | ------------------------------ | ------- | --------------- |
+| `children` | `ReactNode` | — | Cell content |
| `xstyle` | `StyleXStyles \| StyleXStyles` | — | Style overrides |
### XDSTableHeaderCell
@@ -141,7 +187,60 @@ Unstyled table with colgroup, plugin pipeline, and components prop for custom re
## Usage Patterns
-### Data-driven table
+### Rich cell content with renderCell
+
+Use `renderCell` to compose XDS components inside table cells. This is the
+recommended pattern for any table that displays more than plain text.
+
+```tsx
+const columns = [
+ {
+ key: 'transaction',
+ header: 'Transaction',
+ renderCell: item => (
+ <XDSVStack gap="space1">
+ <XDSText type="body" weight="semibold">
+ {item.description}
+ </XDSText>
+ <XDSText type="supporting" color="secondary">
+ {item.date}
+ </XDSText>
+ </XDSVStack>
+ ),
+ },
+ {
+ key: 'amount',
+ header: 'Amount',
+ width: pixel(120),
+ renderCell: item => (
+ <XDSText
+ type="body"
+ weight="semibold"
+ color={item.amount > 0 ? 'positive' : 'primary'}>
+ {item.amount > 0 ? '+' : ''}
+ {item.amount.toFixed(2)}
+ </XDSText>
+ ),
+ },
+ {
+ key: 'status',
+ header: 'Status',
+ width: pixel(140),
+ renderCell: item => (
+ <XDSHStack gap="space2" align="center">
+ <XDSStatusDot status={statusMap[item.status]} />
+ <XDSBadge variant={badgeMap[item.status]}>{item.status}</XDSBadge>
+ </XDSHStack>
+ ),
+ },
+];
+
+<XDSTable data={transactions} columns={columns} hasHover dividers="rows" />;
+```
+
+### Data-driven table (plain text)
+
+For simple tables where plain text is sufficient, columns default to `String(item[key])`:
```tsx
<XDSTable
@@ -166,11 +265,20 @@ Unstyled table with colgroup, plugin pipeline, and components prop for custom re
### Children mode
+For fully custom row layouts, use children mode with XDSTableRow and XDSTableCell:
+
```tsx
<XDSTable density="balanced" dividers="rows" isStriped hasHover>
<XDSTableRow>
- <XDSTableCell>Alice</XDSTableCell>
- <XDSTableCell>30</XDSTableCell>
+ <XDSTableCell>
+ <XDSHStack gap="space2" align="center">
+ <XDSAvatar name="Alice" size="small" />
+ <XDSText weight="semibold">Alice</XDSText>
+ </XDSHStack>
+ </XDSTableCell>
+ <XDSTableCell>
+ <XDSBadge variant="success">Active</XDSBadge>
+ </XDSTableCell>
</XDSTableRow>
</XDSTable>
```
diff --git a/packages/core/src/Table/XDSTable.tsx b/packages/core/src/Table/XDSTable.tsx
index 60d290e2f4..b144239e95 100644
--- a/packages/core/src/Table/XDSTable.tsx
+++ b/packages/core/src/Table/XDSTable.tsx
@@ -180,17 +180,30 @@ function XDSTableInner<T extends Record<string, unknown>>(
* Density, dividers, striped rows, and hover effects are applied via
* design tokens in the component styles.
*
+ * @compositionHint Use renderCell on columns to compose rich cell content.
+ * Combine with XDSBadge (status labels), XDSStatusDot (colored indicators),
+ * XDSText (formatted values), XDSAvatar (user cells), and XDSHStack/XDSVStack
+ * (multi-element cell layouts). Without renderCell, cells render as plain text.
+ *
* @example
* ```
* <XDSTable
* data={users}
* columns={[
- * { key: 'name', header: 'Name' },
- * { key: 'email', header: 'Email' },
+ * { key: 'name', header: 'Name', renderCell: (u) => (
+ * <XDSHStack gap="space2" align="center">
+ * <XDSAvatar name={u.name} size="small" />
+ * <XDSText weight="semibold">{u.name}</XDSText>
+ * </XDSHStack>
+ * )},
+ * { key: 'status', header: 'Status', renderCell: (u) => (
+ * <XDSBadge variant={u.active ? 'success' : 'error'}>
+ * {u.active ? 'Active' : 'Inactive'}
+ * </XDSBadge>
+ * )},
* ]}
* density="compact"
* dividers="grid"
- * isStriped
* hasHover
* />
* ```
diff --git a/packages/core/src/Table/types.ts b/packages/core/src/Table/types.ts
index 80f1a98347..1077eced29 100644
--- a/packages/core/src/Table/types.ts
+++ b/packages/core/src/Table/types.ts
@@ -60,8 +60,28 @@ export interface XDSTableColumn<T extends Record<string, unknown>> {
/** Column width. Defaults to `proportional(1)`. */
width?: ColumnWidth;
/**
- * Custom cell renderer. Receives the row item.
- * Defaults to `String(item[key])`.
+ * Custom cell renderer. Receives the row item and returns rich JSX content.
+ * Defaults to `String(item[key])` — use renderCell for rich content like
+ * badges, status dots, formatted text, icons, or composed layouts.
+ *
+ * @compositionHint Use renderCell to compose rich table cells:
+ * - XDSBadge for status labels (success/warning/error variants)
+ * - XDSStatusDot for colored indicators
+ * - XDSText with color="positive"|"negative" for formatted values
+ * - XDSHStack to combine multiple elements in a cell
+ * - XDSAvatar for user/entity cells
+ *
+ * @example
+ * ```tsx
+ * renderCell: (item) => (
+ * <XDSHStack gap="space2" align="center">
+ * <XDSStatusDot status={item.isActive ? 'positive' : 'negative'} />
+ * <XDSBadge variant={item.isActive ? 'success' : 'error'}>
+ * {item.isActive ? 'Active' : 'Inactive'}
+ * </XDSBadge>
+ * </XDSHStack>
+ * )
+ * ```
*/
renderCell?: (item: T) => ReactNode;
}