Table
Rows of records people compare and act on: transactions, orders, users. A real table with column headers and cells.
Ritla scan of this preview: 41 of 41 checks3 breakpointsScanned
Preview
Mirrored is the same English content laid out right to left: it separates a mirroring bug from a translation one.
Installation
Add the component
npx ritla add tableAlso works with shadcn:
npx shadcn@latest add @ritla/tableDependencies it brings
@phosphor-icons/reactOr copy by hand
Installing by hand copies the component's source into your project. The source comes with a Ritla UI license, so the CLI is the short way to the same files.
Usage
import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@/components/ui/table";<Table> <TableHeader variant="gray"> <TableRow> <TableHead sort="descending" onSort={toggle}>Date</TableHead> <TableHead align="end">Amount</TableHead> </TableRow> </TableHeader> <TableBody> <TableRow> <TableCell>12/09/2026</TableCell> <TableCell numeric>+2,450.00 JOD</TableCell> </TableRow> </TableBody></Table>Examples
Row selection
A checkbox in the first column (CheckboxBox with a name), an avatar and a subtitle in the cell; a checked row keeps its fill.
White header and info
variant="white" (the default), a leading icon, an info tooltip, and no column dividers (dividers={false}).
Data table
A toolbar (search, filters, export); the select-all checkbox inside the header cell through leading; TableSelectionBar for bulk actions, its count announced in the page numerals; row actions in the last cell (two inline at most, the rest under More, each naming its row); TablePagination under the table.
Expandable rows
TableExpandToggle in the first cell opens TableExpandedRow under its row, after the toggle column. Keep a closed row with hidden so find-in-page still reaches it.
Sticky columns
sticky="start" keeps the first column in view and sticky="end" the actions column, set on both TableHead and TableCell. The shade shows only once something scrolls underneath. Scroll the table sideways.
API reference
Table
| Prop | Type | Default | Description |
|---|---|---|---|
dividers | boolean | true | Figma's Show divider: a line at each column's end. |
aria-label / TableCaption | string / ReactNode | None | The table's name for screen readers. |
TableHeader
| Prop | Type | Default | Description |
|---|---|---|---|
variant | "white" | "gray" | "white" | Figma's Color on Table header cell. |
TableRow
| Prop | Type | Default | Description |
|---|---|---|---|
selected | boolean | false | Figma's State = Hover/selected, kept on for a checked row. |
TableHead
| Prop | Type | Default | Description |
|---|---|---|---|
children | ReactNode | None | Figma's Label. |
sort | "none" | "ascending" | "descending" | None | A sortable column and its state; leave it out on the rest. |
onSort / sortHref | () => void / string | None | A sort button (client code) or a link (server pages). |
leadingIcon | IconComponent | None | Figma's Leading icon. |
info | ReactNode | None | Figma's Show tooltip: an info tooltip after the label. |
align | "start" | "end" | "start" | end for numeric columns. |
leading | ReactNode | None | Figma's Show checkbox: a control before the label (the select-all checkbox), outside the sort button. |
sticky | "start" | "end" | None | Keeps the column in view while the table scrolls sideways. |
TableCell
| Prop | Type | Default | Description |
|---|---|---|---|
children | ReactNode | None | Figma's Cell Title. |
subtitle | ReactNode | None | Figma's Cell Subtitle. |
leading / trailing | ReactNode | None | Before and after the text: an avatar, icon, tag, checkbox… |
numeric | boolean | false | An amount or count: at the column's end, in tabular figures, left to right. |
sticky | "start" | "end" | None | As on TableHead; set it on both. |
TableSelectionBar
| Prop | Type | Default | Description |
|---|---|---|---|
count | number | None | How many rows are selected; render the bar while it's above 0. |
onClear | () => void | None | The Clear selection button; without it, no button. |
clearLabel / countLabel | ReactNode / (n) => ReactNode | None | Overrides the default words ("3 selected"). |
children | ReactNode | None | The bulk actions: Ghost sm Buttons, Delete with danger. |
TableExpandToggle
| Prop | Type | Default | Description |
|---|---|---|---|
expanded | boolean | None | Whether the details are showing. |
onExpandedChange | (expanded: boolean) => void | None | Called with the next state. |
controls | string | None | The id of its TableExpandedRow. |
label | string | None | The button's name, naming the row ("Details for Omar Haddad"); aria-expanded carries the state. |
TableExpandedRow
| Prop | Type | Default | Description |
|---|---|---|---|
id | string | None | The id its toggle points at. |
colSpan | number | None | The table's column count. |
TablePagination
| Prop | Type | Default | Description |
|---|---|---|---|
pageCount | number | None | How many pages there are. |
page / defaultPage / onPageChange | number / number / (page) => void | None | The current page, from 1. |
pageSize / defaultPageSize / onPageSizeChange | number / number / (size) => void | None | Rows per page. |
pageSizes | number[] | [10, 20, 50] | The sizes to pick from. |
selected / total | number | None | "2 of 248 rows selected"; leave both out to hide it. |
numerals | "latn" | "arab" | None | Numeral system; defaults to RitlaProvider's. |
Usage guidelines
A table compares the same facts across many records. Table, list or cards, aligning text and numbers, headers and sorting, what goes in a row, small screens, how it mirrors in Arabic, and the checks before handoff.
1. Table, list or cards
Use a table when people compare the same facts across many records and act on them: dates, amounts, statuses. When each record is read on its own, or the screen is narrow, a list or cards work better.
| You need to | Use | Why |
|---|---|---|
| Compare the same fields across many records | Table | Columns make comparison and sorting easy. |
| Read records one at a time, with a title and a summary | List | Each row is a small story, not a set of fields. |
| Show a few rich items with images | Cards | Visual items don't fit in cells. |
| Show records on a phone | List, or a table that becomes cards | Columns don't fit a narrow screen. |
2. Align text and numbers
Text aligns to the inline start. Amounts and other numbers people compare line up at the decimals, with the same number of decimals in every row, so digits line up by place value. Use one date format and one currency format in the whole table.
Amounts line up at the end
Card transactions.
Do
- Right-align amounts and counts so the decimals line up.
- Use the same decimals and currency format in a column.
- Use one date format across the table.
- Keep a column's cells the same width.
Don't
- Align amounts to the start, so 85.500 and 12,400.000 don't line up.
- Mix 1.2k and 1,200 in one column.
- Center text columns.
3. Headers and sorting
Every column has a short header. Show the sort icon only on columns that can be sorted, with the current direction on the sorted one. Put a select-all checkbox in the first header when rows can be selected.
Do
- Keep headers to one or two words.
- Show the sort icon only on sortable columns.
- Sort by the most useful column by default, often the date, newest first.
Don't
- Show a sort icon on every column.
- Write headers that wrap onto two lines.
- Leave people unsure which column the table is sorted by.
4. What goes in a row
One primary value per cell, with an optional subtitle. Statuses go in Tags, people in an avatar with a name, row actions in a menu at the inline end. Design the empty table, loading rows and an error state, and put pagination under the table.
Do
- Put statuses in Tags and people in avatars with names.
- Put row actions in a Menu button at the inline end.
- Design empty, loading and error states.
- Put pagination and the result count under the table.
Don't
- Put several buttons in every row.
- Show raw codes where people expect names.
- Show an empty grid with no message.
5. Small screens
Tables need width. On tablets, let the table scroll sideways and keep the first column fixed. On phones, turn each row into a list item or card that shows the two or three fields that matter most.
Do
- Keep the first column fixed while the rest scroll sideways.
- Switch to list items or cards on phones.
- Keep the same order of fields in both layouts.
Don't
- Squeeze every column into a phone screen.
- Hide important columns without a way to see them.
6. Arabic and RTL
Use the RTL cells in Arabic tables: the first column sits on the right and text aligns right. Amounts don't mirror: their digits read left to right, so they stay right-aligned and line up at the decimals, like a chart's numeric axis. Never mix LTR and RTL cells in one table.
Columns mirror, amounts don't
Card transactions in Arabic.
Before handoff
- Text aligns to the start, amounts line up at the decimals, formats match.
- Sortable columns and the default sort are marked.
- Empty, loading, error and pagination are designed.
- The phone layout is designed.
- Arabic tables use RTL cells only.
Accessibility
Keyboard
Keys are written for left-to-right. In right-to-left the arrow keys swap: the one pointing toward the reading direction moves forward.
| Key | Action |
|---|---|
| Tab | Reaches the sort buttons and the controls inside cells only. |
| EnterSpace | Sorts the column. |
ARIA
- A real table:
table,th scope="col"andtd, so screen readers pair each cell with its header. - A sortable column is a button inside a
ththat carriesaria-sort. - Selection checkboxes have names ("Select all", the row's name).
- The selection bar is a region named "Selection"; its count is announced politely as it changes.
- The expand toggle carries
aria-expandedandaria-controls; its name stays the same and names the row. - Table pagination is a named
nav; the end buttons stay focusable while disabled, so focus isn't lost on page 1, and "Page 1 of 25" is announced politely.
Do
- A header cell for every column.
aria-sorton the sorted column.- Name row checkboxes after the row: “Select Cozmo, 3 March”.
- A visible title or a caption.
Don't
- Build tables from generic boxes instead of table markup.
- Rely on color alone for negative amounts; add a minus sign.
Arabic and RTL notes
Mirrors
- The first column sits on the right, text at the cell's start (its right), the divider at its end (its left).
- Numeric columns sit at the cell's end (its left in Arabic).
- A
startsticky column sits on the right with its shade to its left; the closed expand toggle points left; the pagination carets flip (Next points left).
Does not mirror
- Amounts stay left to right, so the sign stays next to the number.
- Emails and IDs in
<bdi dir="ltr">.
- Numerals
- Dates and amounts in the chosen numerals; one format per column. The selection count and the pagination follow the page numerals, and Arabic's row noun agrees with the number (٣ صفوف، ١١ صفًا، ١٠٠ صف).
- Arabic typography
body-12Semibold headers,body-14Medium cells,body-12subtitles.- Mixed-direction text
- Don't mix LTR and RTL cells in one table: the direction comes from the page.
Do
- RTL header cells and cells for the whole table.
- Columns start on the right, in the same order as English.
- Keep amounts right-aligned so the decimals line up; digits read left to right.
- Put the currency in the header when the whole column shares it.
- Keep numbers, IBANs and codes left to right inside their cells.
Don't
- Mix LTR and RTL cells in one table.
- Mirror amount columns to the left, so place values stop lining up.
Checks it passes
The Ritla checks this component satisfies by construction. Used as documented, it does not bring these defects onto your page.
- Unisolated bidi hazards: phones, emails, Latin tokens inside Arabic text
- text-align: left explicitly set on majority-Arabic text
- Clipped text: content wider than its box with overflow hidden and no ellipsis
- Fixed-pixel-width container whose Arabic text exceeds the space
- Arabic text falling back past the declared font family (measured, declared, or a webfont that failed to load)
- letter-spacing applied to Arabic text (breaks the connected script)