Table

API and Development

View SourceOpens in a new tab Submit IssueOpens in a new tab

Table displays structured data in a simple, semantic table format, providing full control over layout and styling without built-in data management features. It provides a lightweight, semantic table component built on Radix UI's Table primitives. It renders tabular data with proper HTML structure, supports flexible cell alignment and sizing, and offers complete control over rendering without any built-in data management features like sorting, filtering, or pagination. It's the foundation component that DataTable builds upon, ideal for simple displays, static content, or when you need complete control over table structure and styling.

When to Use Table vs DataTable

Use Table (from @prepared911/ui) when you need:

Simple, static data display (< 50 rows)
No sorting, filtering, or pagination requirements
Custom table layouts or complex styling
Full manual control over table structure
Lightweight tables with minimal overhead
Simple data presentation without interactions
Building custom table functionality from scratch
Rendering markdown or documentation tables

Use DataTable (from @prepared911/ui/data-table) when you need: (see the Data table package API for generated props, Storybook links, and a live preview)

Sorting, filtering, or pagination functionality
Row selection with bulk actions
Expandable rows or hierarchical data
Action menus on each row
Loading states and skeleton screens
Server-side or client-side data management
Large datasets (100+ rows)
Advanced table features and interactions

Props

Table (generated)

Name	Type	Default	Description
`aria-description`	`LocalizedMessage`	—	Extended description for assistive tech.
`aria-label`	`LocalizedMessage`	—	Accessible name when the visible label is insufficient.
`aria-placeholder`	`LocalizedMessage`	—	Hint for an empty control.
`children`	`ReactNode`	—	Table content: {@link TableHeader } and {@link TableBody }.
`className`	`string`	—	Classes appended after generated classes. Put overrides in `@layer chroma.overrides`.
`ref`	`Ref<HTMLTableElement>`	—	Ref to the `table`.
`shrink`	`boolean`	`false`	When true, columns size to their content (`table-layout: auto`). Otherwise the layout is fixed and columns share the inline size equally unless a column sets its own.
`title`	`LocalizedMessage`	—	Native tooltip; accessibility hint, not visible UI title text.

Storybook

Interactive examples and edge cases live in Storybook (not duplicated here).

DefaultOpens in a new tab

Table

Name	Default	Description
`shrink`	`false`	Whether to use auto layout (shrink) or fixed layout. When `true`, table uses auto layout; when `false`, uses fixed layout.
`children`	`required`	Table structure components (`TableHeader`, `TableBody`, etc.).

TableCell

Name	Default	Description
`type`	`TableCellType.Default`	Cell type determining semantic meaning. Options: `Default`, `ColumnHeader`, `RowHeader`.
`justify`		Text alignment within the cell. Options: `Start`, `Center`, `End`.
`width`		Fixed width for the cell (e.g., `"20rem"`, `"300px"`).
`minWidth`		Minimum width for the cell.
`maxWidth`		Maximum width for the cell.
`colSpan`		Number of columns the cell spans.
`children`	`required`	Cell content.

Default

Shrink

With cell alignment

Scrolling table

Table Layout

Control how the table handles column sizing.

Fixed Layout

Use fixed layout for consistent column widths (default).

Column widths are fixed according to the specified width prop.

Auto Layout (Shrink)

Use auto layout to let content determine column widths.

Columns automatically size based on content.

Cell Types

Use appropriate cell types for semantic meaning.

Column Headers

Mark column headers for accessibility.

Column headers provide semantic meaning and improve accessibility.

Row Headers

Mark the first cell in each row as a row header.

Row headers help identify row content, especially for screen readers.

Column Widths

Control column widths explicitly.

Flexible Widths

Use min and max width constraints.

Colspan

Span cells across multiple columns.

Table with Scrollable Content

Wrap tables in scrollable containers for long content.

Scrollable containers enable horizontal and vertical scrolling.

Table with Custom Content

Render complex content within cells.

Cells can contain any React components.

Table with Styled Cells

Apply custom styling through components.

Use Text components for styled cell content.

Responsive Table

Handle table overflow on smaller screens.

Horizontal scrolling allows tables to adapt to narrow viewports.

Table For Documentation

Table for Documentation

Use tables for structured documentation content.

Tables work well for API documentation, feature comparisons, or data specifications.

Empty State

Handle empty tables appropriately.

Provide clear messaging when tables are empty.

Dynamic Rows

Generate rows dynamically from data.

Use map to generate rows from arrays.

Nested Content

Include nested structures in cells.

Cells can contain complex nested layouts.

Cell Alignment

Control text alignment within cells.

Left Alignment

Align content to the start (left in LTR layouts).

Center Alignment

Center content within cells.

Right Alignment

Align content to the end (right in LTR layouts).

Right alignment is useful for numbers, dates, or action buttons.

Table / Usage

Accessibility / General

Table

API and Development

View SourceOpens in a new tab Submit IssueOpens in a new tab

When to Use Table vs DataTable

Use Table (from @prepared911/ui) when you need:

Simple, static data display (< 50 rows)
No sorting, filtering, or pagination requirements
Custom table layouts or complex styling
Full manual control over table structure
Lightweight tables with minimal overhead
Simple data presentation without interactions
Building custom table functionality from scratch
Rendering markdown or documentation tables

Use DataTable (from @prepared911/ui/data-table) when you need: (see the Data table package API for generated props, Storybook links, and a live preview)

Sorting, filtering, or pagination functionality
Row selection with bulk actions
Expandable rows or hierarchical data
Action menus on each row
Loading states and skeleton screens
Server-side or client-side data management
Large datasets (100+ rows)
Advanced table features and interactions

Props

Table (generated)

Name	Type	Default	Description
`aria-description`	`LocalizedMessage`	—	Extended description for assistive tech.
`aria-label`	`LocalizedMessage`	—	Accessible name when the visible label is insufficient.
`aria-placeholder`	`LocalizedMessage`	—	Hint for an empty control.
`children`	`ReactNode`	—	Table content: {@link TableHeader } and {@link TableBody }.
`className`	`string`	—	Classes appended after generated classes. Put overrides in `@layer chroma.overrides`.
`ref`	`Ref<HTMLTableElement>`	—	Ref to the `table`.
`shrink`	`boolean`	`false`	When true, columns size to their content (`table-layout: auto`). Otherwise the layout is fixed and columns share the inline size equally unless a column sets its own.
`title`	`LocalizedMessage`	—	Native tooltip; accessibility hint, not visible UI title text.

Storybook

Interactive examples and edge cases live in Storybook (not duplicated here).

DefaultOpens in a new tab

Table

Name	Default	Description
`shrink`	`false`	Whether to use auto layout (shrink) or fixed layout. When `true`, table uses auto layout; when `false`, uses fixed layout.
`children`	`required`	Table structure components (`TableHeader`, `TableBody`, etc.).

TableCell

Name	Default	Description
`type`	`TableCellType.Default`	Cell type determining semantic meaning. Options: `Default`, `ColumnHeader`, `RowHeader`.
`justify`		Text alignment within the cell. Options: `Start`, `Center`, `End`.
`width`		Fixed width for the cell (e.g., `"20rem"`, `"300px"`).
`minWidth`		Minimum width for the cell.
`maxWidth`		Maximum width for the cell.
`colSpan`		Number of columns the cell spans.
`children`	`required`	Cell content.

Default

Shrink

With cell alignment

Scrolling table

Table Layout

Control how the table handles column sizing.

Fixed Layout

Use fixed layout for consistent column widths (default).

Column widths are fixed according to the specified width prop.

Auto Layout (Shrink)

Use auto layout to let content determine column widths.

Columns automatically size based on content.

Cell Types

Use appropriate cell types for semantic meaning.

Column Headers

Mark column headers for accessibility.

Column headers provide semantic meaning and improve accessibility.

Row Headers

Mark the first cell in each row as a row header.

Row headers help identify row content, especially for screen readers.

Column Widths

Control column widths explicitly.

Flexible Widths

Use min and max width constraints.

Colspan

Span cells across multiple columns.

Table with Scrollable Content

Wrap tables in scrollable containers for long content.

Scrollable containers enable horizontal and vertical scrolling.

Table with Custom Content

Render complex content within cells.

Cells can contain any React components.

Table with Styled Cells

Apply custom styling through components.

Use Text components for styled cell content.

Responsive Table

Handle table overflow on smaller screens.

Horizontal scrolling allows tables to adapt to narrow viewports.

Table For Documentation

Table for Documentation

Use tables for structured documentation content.

Tables work well for API documentation, feature comparisons, or data specifications.

Empty State

Handle empty tables appropriately.

Provide clear messaging when tables are empty.

Dynamic Rows

Generate rows dynamically from data.

Use map to generate rows from arrays.

Nested Content

Include nested structures in cells.

Cells can contain complex nested layouts.

Cell Alignment

Control text alignment within cells.

Left Alignment

Align content to the start (left in LTR layouts).

Center Alignment

Center content within cells.

Right Alignment

Align content to the end (right in LTR layouts).

Right alignment is useful for numbers, dates, or action buttons.

Table / Usage

Accessibility / General