Table

Introduction

The Table component provides a highly flexible and feature-rich data table for displaying, sorting, searching, selecting, and paginating tabular data. It supports custom cell rendering, multiple visual variants, selectable rows, loading and empty states, and advanced customization for headers, footers, and row styling. The API is designed to be both declarative and extensible, making it suitable for dashboards, admin panels, and any data-driven UI.

Import

import { Table } from '@odyssee/components';

LiveCodeEditor examples

Basic Table

Code Éditable

Résultat

Striped, Bordered, and Rounded Variants

Code Éditable

Résultat

Selectable Rows

Code Éditable

Résultat

Sortable and Searchable

Code Éditable

Résultat

Paginated Table

Code Éditable

Résultat

Custom Cell Render

Code Éditable

Résultat

Props

Prop	Type	Default	Description
columns	Table.Column<T>[]	—	Array of column definitions (see below for shape).
data	T[]	—	Array of row data.
variant	"default" | "striped" | "bordered" | "rounded" | "shadow"	"default"	Visual style of the table.
theadVariant	"default" | "gray" | "divided"	"default"	Style of the table header.
size	"sm" | "md" | "lg"	"md"	Table size (affects row/cell padding).
hoverable	boolean	false	Highlight rows on hover.
selectable	boolean	false	Enable row selection (checkboxes).
selectedRows	Signal<(string | number)[]> | (string | number)[]	—	Controlled selected row IDs.
onSelectionChange	(selected: (string | number)[]) => void	—	Callback when selection changes.
sortable	boolean	false	Enable sorting on sortable columns.
sortBy	Signal<string | null> | string | null	—	Controlled sort column key.
sortDirection	Signal<"asc" | "desc" | null> | "asc" | "desc" | null	—	Controlled sort direction.
onSort	(column: string, direction: "asc" | "desc" | null) => void	—	Callback when sorting changes.
searchable	boolean	false	Enable search input above the table.
searchValue	Signal<string> | string	—	Controlled search value.
searchPlaceholder	string	—	Placeholder for the search input.
onSearch	(value: string) => void	—	Callback when search value changes.
paginated	boolean	false	Enable pagination controls.
currentPage	Signal<number> | number	—	Controlled current page.
pageSize	number	—	Number of rows per page.
totalPages	number	—	Total number of pages.
onPageChange	(page: number) => void	—	Callback when page changes.
caption	string	—	Table caption (displayed above the table).
showFooter	boolean	—	Show the table footer.
footerContent	JSX.Element	—	Custom footer content.
headless	boolean	false	Hide the table header.
loading	boolean | Signal<boolean>	false	Show loading state (skeleton rows).
loadingRows	number	5	Number of skeleton rows to show when loading.
emptyMessage	string | JSX.Element	—	Message to display when there is no data.
onRowClick	(row: T, index: number) => void	—	Callback when a row is clicked.
rowClassName	(row: T, index: number) => string	—	Function to add custom classes to rows.
rowKey	keyof T	—	Property to use as the row key (defaults to id if present).
className	string	—	Additional CSS classes for the table container.
...rest	—	—	Any other props are spread to the root container.

Table.Column shape

Prop	Type	Default	Description
key	string	—	Unique key for the column (matches property in row data).
label	string	—	Column header label.
width	string	—	CSS width for the column (e.g., "120px" or "20%").
align	"start" | "center" | "end"	—	Cell alignment.
sortable	boolean	false	Whether the column is sortable.
render	(value, row, index) => JSX.Element | string	—	Custom cell renderer for this column.
headerRender	() => JSX.Element | string	—	Custom header renderer for this column.
className	string	—	Additional classes for cells in this column.
headerClassName	string	—	Additional classes for the column header.

Implementation notes

• The Table component is fully controlled or uncontrolled for selection, sorting, searching, and pagination.
• Supports custom cell and header rendering via render and headerRender in columns.
• Visual variants (striped, bordered, rounded, shadow) and header variants (gray, divided) are available.
• Loading and empty states are handled natively.
• Row selection, sorting, searching, and pagination can be combined.
• The rowClassName prop allows dynamic row styling (e.g., highlight inactive rows).
• The table is responsive and supports custom sizing via the size prop.

Accessibility

• The table uses semantic <table>, <thead>, <tbody>, <tr>, <th>, and <td> elements.
• Checkbox selection is accessible via keyboard and screen readers.
• Sorting and pagination controls are accessible and labeled.
• The caption is rendered with the <caption> element for assistive technologies.
• Ensure custom cell renderers and interactive content are accessible and keyboard-navigable.

Best practices

• Use concise, descriptive column labels.
• Prefer unique id or rowKey for row identification.
• Use variant and theadVariant to match your application's style.
• For large datasets, enable pagination and search for better usability.
• Use custom cell renderers for avatars, badges, or action buttons.
• Avoid overloading the table with too many columns; keep it readable and focused.

Related links

• Pagination documentation
• Badge documentation
• Button documentation
• Odyssee Components documentation