# React Native Table

> A React Native table for iOS, Android and the web: columns as data, custom cells, sortable headers, pressable and striped rows, horizontal scroll, empty state, and table roles for screen readers. No dependencies.

# Table

Rows and columns of data: orders, invoices, users. Columns come as data, cells draw as text or any node, headers sort when `sortable`, and rows can be pressed. It draws every row, so keep it to a page at a time: pair it with [Pagination](./pagination) for long lists.

```tsx
import { Table } from 'patine-ui';
```

```tsx live
import { Avatar, Badge, HStack, Pagination, Table, Text, VStack } from 'patine-ui';

const INVOICES = [
  { id: 'INV-1042', customer: 'Maya Cohen', status: 'Paid', method: 'Visa ···· 4242', amount: 250 },
  { id: 'INV-1043', customer: 'Daniel Okafor', status: 'Pending', method: 'PayPal', amount: 150 },
  { id: 'INV-1044', customer: 'Ana Lucía Pérez', status: 'Overdue', method: 'Bank transfer', amount: 350 },
  { id: 'INV-1045', customer: 'Noah Kim', status: 'Paid', method: 'Visa ···· 1881', amount: 450 },
  { id: 'INV-1046', customer: 'Priya Raman', status: 'Paid', method: 'Apple Pay', amount: 550 },
];
const VARIANT = { Paid: 'success', Pending: 'secondary', Overdue: 'destructive' };

export default function Example() {
  const [selected, setSelected] = React.useState(null);
  return (
    <VStack gap="md">
      <Table
        caption="Recent invoices"
        data={INVOICES}
        onRowPress={(row) => setSelected(row.id)}
        defaultSort={{ key: 'amount', direction: 'desc' }}
        columns={[
          {
            key: 'customer',
            title: 'Customer',
            flex: 2,
            sortable: true,
            render: (row) => (
              <HStack gap="sm">
                <Avatar name={row.customer} size="sm" />
                <Text size="sm">{row.customer}</Text>
              </HStack>
            ),
          },
          { key: 'status', title: 'Status', render: (row) => <Badge variant={VARIANT[row.status]}>{row.status}</Badge> },
          { key: 'amount', title: 'Amount', align: 'right', sortable: true, render: (row) => <Text size="sm" weight="medium">${row.amount}.00</Text> },
        ]}
      />
      <Text size="sm" color="textSecondary">{selected ? `Opened ${selected}` : 'Press a row to open it.'}</Text>
    </VStack>
  );
}
```

## Example: a sales leaderboard

A sales team's quarter: sort by deals or revenue, the rank follows the sort, and the table scrolls sideways on a phone instead of squeezing its columns.

```tsx live wide
import { useState } from 'react';
import { Avatar, HStack, Progress, Table, Text, VStack } from 'patine-ui';

const REPS = [
  { name: 'Maya Cohen', region: 'EMEA', deals: 42, revenue: 318000, quota: 300000 },
  { name: 'Daniel Okafor', region: 'Americas', deals: 38, revenue: 352000, quota: 340000 },
  { name: 'Ana Lucía Pérez', region: 'Americas', deals: 51, revenue: 287000, quota: 320000 },
  { name: 'Noah Kim', region: 'APAC', deals: 29, revenue: 241000, quota: 260000 },
  { name: 'Priya Raman', region: 'EMEA', deals: 33, revenue: 296000, quota: 280000 },
];
const euro = (n: number) => `€${Math.round(n / 1000)}k`;

export default function Example() {
  const [sort, setSort] = useState<{ key: string; direction: 'asc' | 'desc' }>({ key: 'revenue', direction: 'desc' });
  const ranked = [...REPS].sort((a, b) => (b[sort.key] - a[sort.key]) * (sort.direction === 'desc' ? 1 : -1));
  return (
    <VStack gap="sm" style={{ width: '100%' }}>
      <Table
        caption="Q4 so far"
        style={{ width: '100%' }}
        data={ranked}
        keyExtractor={(r) => r.name}
        sort={sort}
        onSortChange={setSort}
        manualSort
        striped
        minWidth={520}
        columns={[
          { key: 'rank', title: '#', width: 36, render: (row) => <Text size="sm" color="textSecondary">{ranked.indexOf(row) + 1}</Text> },
          {
            key: 'name',
            title: 'Rep',
            flex: 2,
            render: (row) => (
              <HStack gap="sm">
                <Avatar name={row.name} size="sm" />
                <VStack>
                  <Text size="sm" weight="medium">{row.name}</Text>
                  <Text size="xs" color="textSecondary">{row.region}</Text>
                </VStack>
              </HStack>
            ),
          },
          { key: 'deals', title: 'Deals', align: 'right', sortable: true },
          { key: 'revenue', title: 'Revenue', align: 'right', sortable: true, render: (row) => <Text size="sm" weight="medium">{euro(row.revenue)}</Text> },
          {
            key: 'quota',
            title: 'Quota',
            flex: 1.5,
            render: (row) => (
              <VStack gap="xs">
                <Progress value={Math.min(100, (row.revenue / row.quota) * 100)} accessibilityLabel={`${row.name}, quota`} />
                <Text size="xs" color={row.revenue >= row.quota ? 'success' : 'textSecondary'}>{Math.round((row.revenue / row.quota) * 100)}%</Text>
              </VStack>
            ),
          },
        ]}
      />
    </VStack>
  );
}
```

## Columns

Each column has a `key` and a `title`. The cell shows `row[key]`, or `accessor(row)`, as text; `render(row, index)` draws anything instead. `width` fixes a column in points; otherwise columns share the free width by `flex` (1 each). Put numbers on the right with `align: 'right'`.

## Sorting

`sortable` columns sort when their header is pressed: ascending, then descending, then back to the data's order. Numbers sort by size and text the way people expect ("Item 2" before "Item 10"), with empty cells last. `sort` and `onSortChange` make it controlled; `manualSort` leaves `data` in the order you give it, for sorting on a server.

## Narrow screens

Below `minWidth`, the table scrolls sideways instead of squeezing its columns.

## Designs

- **web**: shadcn's Table: gray header text and a line under each row.
- **Material 3**: a data table: 56dp header, 52dp rows, in an outlined box.
- **iOS**: list-like 44pt rows under a small capitalized header.
- **brand**: an outlined box with a tinted header.

## Accessibility

- A `table` of `row`s, with `columnheader` and `cell` roles. A sortable header is a button with `aria-sort`, and its title shows ↑ or ↓.
- A pressable row is one button read as its cells together, with hover and a focus ring on the web.
- `caption` is a heading read before the table.

## Props

Also takes `View` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `columns` | `{ key, title, align?, width?, flex?, accessor?, render?, sortable? }[]` | — | The columns. |
| `data` | `T[]` | — | The rows. |
| `keyExtractor` | `(row, index) => string` | `row.id`, else the index | Each row's key. |
| `onRowPress` | `(row, index) => void` | — | Makes rows pressable. |
| `caption` | `ReactNode` | — | A title, read first. |
| `striped` | `boolean` | `false` | Tints every other row. |
| `sort` | `{ key, direction } \| null` | — | Controlled sort. |
| `defaultSort` | `{ key, direction } \| null` | `null` | Uncontrolled sort. |
| `onSortChange` | `(sort) => void` | — | Called when a header is pressed. |
| `manualSort` | `boolean` | `false` | Keep `data`'s order. |
| `emptyText` | `ReactNode` | `'No results.'` | Shown with no rows. |
| `minWidth` | `number` | — | Scrolls sideways below this width. |
| `styles` | `{ table?, header?, headerCell?, row?, cell?, caption? }` | — | Slot styles. |
| `theme`, `design` | | | As every component. |
