```tsx title="components/table-1.tsx"
// import from your project: import Demo from '@/components/table-1'
import {
  Table,
  TableBody,
  TableCaption,
  TableCell,
  TableFooter,
  TableHead,
  TableHeader,
  TableRow,
} from '@gentleduck/registry-ui/table'

const invoices = [
  {
    invoice: 'INV101',
    paymentMethod: 'Apple Pay',
    paymentStatus: 'Unpaid',
    totalAmount: '$180.00',
  },
  {
    invoice: 'INV102',
    paymentMethod: 'Credit Card',
    paymentStatus: 'Paid',
    totalAmount: '$720.00',
  },
  {
    invoice: 'INV103',
    paymentMethod: 'PayPal',
    paymentStatus: 'Pending',
    totalAmount: '$95.00',
  },
  {
    invoice: 'INV104',
    paymentMethod: 'Bank Transfer',
    paymentStatus: 'Paid',
    totalAmount: '$1,250.00',
  },
  {
    invoice: 'INV105',
    paymentMethod: 'Debit Card',
    paymentStatus: 'Unpaid',
    totalAmount: '$430.00',
  },
  {
    invoice: 'INV106',
    paymentMethod: 'Apple Pay',
    paymentStatus: 'Pending',
    totalAmount: '$610.00',
  },
  {
    invoice: 'INV107',
    paymentMethod: 'Google Pay',
    paymentStatus: 'Paid',
    totalAmount: '$390.00',
  },
]

export default function Demo() {
  return (
    <Table>
      <TableCaption>A list of your recent invoices.</TableCaption>
      <TableHeader>
        <TableRow className="[&_th]:py-2">
          <TableHead className="w-[100px]">Invoice</TableHead>
          <TableHead>Status</TableHead>
          <TableHead>Method</TableHead>
          <TableHead className="text-right">Amount</TableHead>
        </TableRow>
      </TableHeader>
      <TableBody>
        {invoices.map((invoice) => (
          <TableRow key={invoice.invoice} className="[&_td]:py-2">
            <TableCell className="font-medium">{invoice.invoice}</TableCell>
            <TableCell>{invoice.paymentStatus}</TableCell>
            <TableCell>{invoice.paymentMethod}</TableCell>
            <TableCell className="text-right">{invoice.totalAmount}</TableCell>
          </TableRow>
        ))}
      </TableBody>
      <TableFooter>
        <TableRow className="[&_td]:py-2">
          <TableCell colSpan={3}>Total</TableCell>
          <TableCell className="text-right">$2,500.00</TableCell>
        </TableRow>
      </TableFooter>
    </Table>
  )
}
```

## Philosophy

HTML tables are semantically powerful but visually bland. Our Table components add consistent styling while preserving the native table structure  -  `

## Installation

CLI
Manual

```bash
npx @gentleduck/cli add table
```

Install the following dependencies:

```bash
npm install @gentleduck/libs
```

Copy and paste the following code into your project.

Update the import paths to match your project setup.

## Usage

```tsx showLineNumbers
import {
  Table,
  TableBody,
  TableCaption,
  TableCell,
  TableHead,
  TableHeader,
  TableRow,
} from "@/components/ui/table"
```

```tsx showLineNumbers
<Table>
  <TableCaption>A list of your recent invoices.</TableCaption>
  <TableHeader>
    <TableRow>
      <TableHead className="w-[100px]">Invoice</TableHead>
      <TableHead>Status</TableHead>
      <TableHead>Method</TableHead>
      <TableHead className="text-right">Amount</TableHead>
    </TableRow>
  </TableHeader>
  <TableBody>
    <TableRow>
      <TableCell className="font-medium">INV001</TableCell>
      <TableCell>Paid</TableCell>
      <TableCell>Credit Card</TableCell>
      <TableCell className="text-right">$250.00</TableCell>
    </TableRow>
  </TableBody>
</Table>
```

## Examples

### Data Table

You can use the `` component to build more complex data tables. Combine it with
[@gentleduck/table](https://github.com/gentleeduck/gentleduck/tree/master/packages/duck-table) to create tables with sorting, filtering and pagination.

See the [Data Table](/duck-ui/components/data-table) documentation for more information.

You can also see data-table examples in the [Blocks Library](/blocks).

## Component Composition

## RTL Support

Direction is resolved through the shared primitives direction module. Use a local `dir="rtl"` override when the component exposes it, or set `DirectionProvider` at app/root level for global RTL/LTR behavior.

```tsx title="components/table-2.tsx"
// import from your project: import Demo from '@/components/table-2'
import {
  Table,
  TableBody,
  TableCaption,
  TableCell,
  TableFooter,
  TableHead,
  TableHeader,
  TableRow,
} from '@gentleduck/registry-ui/table'

const invoices = [
  {
    invoice: 'INV101',
    paymentMethod: 'Apple Pay',
    paymentStatus: 'غير مدفوع',
    totalAmount: '$180.00',
  },
  {
    invoice: 'INV102',
    paymentMethod: 'بطاقة ائتمان',
    paymentStatus: 'مدفوع',
    totalAmount: '$720.00',
  },
  {
    invoice: 'INV103',
    paymentMethod: 'PayPal',
    paymentStatus: 'قيد الانتظار',
    totalAmount: '$95.00',
  },
  {
    invoice: 'INV104',
    paymentMethod: 'تحويل بنكي',
    paymentStatus: 'مدفوع',
    totalAmount: '$1,250.00',
  },
  {
    invoice: 'INV105',
    paymentMethod: 'بطاقة خصم',
    paymentStatus: 'غير مدفوع',
    totalAmount: '$430.00',
  },
  {
    invoice: 'INV106',
    paymentMethod: 'Apple Pay',
    paymentStatus: 'قيد الانتظار',
    totalAmount: '$610.00',
  },
  {
    invoice: 'INV107',
    paymentMethod: 'Google Pay',
    paymentStatus: 'مدفوع',
    totalAmount: '$390.00',
  },
]

export default function Demo() {
  return (
    <Table dir="rtl">
      <TableCaption>{'قائمة بفواتيرك الأخيرة.'}</TableCaption>
      <TableHeader>
        <TableRow className="[&_th]:py-2">
          <TableHead className="w-[100px]">{'الفاتورة'}</TableHead>
          <TableHead>{'الحالة'}</TableHead>
          <TableHead>{'طريقة الدفع'}</TableHead>
          <TableHead className="text-left">{'المبلغ'}</TableHead>
        </TableRow>
      </TableHeader>
      <TableBody>
        {invoices.map((invoice) => (
          <TableRow key={invoice.invoice} className="[&_td]:py-2">
            <TableCell className="font-medium">{invoice.invoice}</TableCell>
            <TableCell>{invoice.paymentStatus}</TableCell>
            <TableCell>{invoice.paymentMethod}</TableCell>
            <TableCell className="text-left">{invoice.totalAmount}</TableCell>
          </TableRow>
        ))}
      </TableBody>
      <TableFooter>
        <TableRow className="[&_td]:py-2">
          <TableCell colSpan={3}>{'الإجمالي'}</TableCell>
          <TableCell className="text-left">$2,500.00</TableCell>
        </TableRow>
      </TableFooter>
    </Table>
  )
}
```

## Motion

} title="Alpha: Motion Compositions" tone="warning">
  Motion components work standalone, but some compositions may behave unexpectedly — this is still under active development. If you find a broken composition, please [file an issue](https://github.com/gentleeduck/gentleduck/issues).

Use `MotionTable` and `MotionTableRow` for staggered entrance animations powered by [motion](https://motion.dev). The table fades in with scale and blur, and each row staggers by 50ms via the `index` prop.

```tsx title="components/table-3.tsx"
// import from your project: import Demo from '@/components/table-3'
import {
  MotionTable,
  MotionTableRow,
  TableBody,
  TableCaption,
  TableCell,
  TableFooter,
  TableHead,
  TableHeader,
} from '@gentleduck/registry-ui/table'

const invoices = [
  { invoice: 'INV101', paymentMethod: 'Apple Pay', paymentStatus: 'Unpaid', totalAmount: '$180.00' },
  { invoice: 'INV102', paymentMethod: 'Credit Card', paymentStatus: 'Paid', totalAmount: '$720.00' },
  { invoice: 'INV103', paymentMethod: 'PayPal', paymentStatus: 'Pending', totalAmount: '$95.00' },
  { invoice: 'INV104', paymentMethod: 'Bank Transfer', paymentStatus: 'Paid', totalAmount: '$1,250.00' },
  { invoice: 'INV105', paymentMethod: 'Debit Card', paymentStatus: 'Unpaid', totalAmount: '$430.00' },
  { invoice: 'INV106', paymentMethod: 'Apple Pay', paymentStatus: 'Pending', totalAmount: '$610.00' },
  { invoice: 'INV107', paymentMethod: 'Google Pay', paymentStatus: 'Paid', totalAmount: '$390.00' },
]

export default function Demo() {
  return (
    <MotionTable>
      <TableCaption>A list of your recent invoices.</TableCaption>
      <TableHeader>
        <MotionTableRow className="[&_th]:py-2" index={0}>
          <TableHead className="w-[100px]">Invoice</TableHead>
          <TableHead>Status</TableHead>
          <TableHead>Method</TableHead>
          <TableHead className="text-right">Amount</TableHead>
        </MotionTableRow>
      </TableHeader>
      <TableBody>
        {invoices.map((invoice, i) => (
          <MotionTableRow key={invoice.invoice} className="[&_td]:py-2" index={i + 1}>
            <TableCell className="font-medium">{invoice.invoice}</TableCell>
            <TableCell>{invoice.paymentStatus}</TableCell>
            <TableCell>{invoice.paymentMethod}</TableCell>
            <TableCell className="text-right">{invoice.totalAmount}</TableCell>
          </MotionTableRow>
        ))}
      </TableBody>
      <TableFooter>
        <MotionTableRow className="[&_td]:py-2" index={invoices.length + 1}>
          <TableCell colSpan={3}>Total</TableCell>
          <TableCell className="text-right">$2,500.00</TableCell>
        </MotionTableRow>
      </TableFooter>
    </MotionTable>
  )
}
```

}>
  Requires the `motion` package. Use `MotionTable` instead of `Table` and `MotionTableRow` instead of `TableRow`. All other sub-components stay the same. The regular components are perfectly fine - this is an optional enhancement.

## API Reference

### Table

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `dir` | `'ltr' \| 'rtl'` | - | Text direction override. Resolved via `useDirection` (`dir` prop -> `DirectionProvider` -> `'ltr'`). |
| `className` | `string` | - | Additional CSS class names |
| `children` | `React.ReactNode` | - | Table content (`TableHeader`, `TableBody`, `TableFooter`, `TableCaption`) |
| `...props` | `React.HTMLProps<HTMLTableElement>` | - | Additional props to spread to the table element |

### TableHeader

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS class names |
| `children` | `React.ReactNode` | - | Header rows |
| `...props` | `React.HTMLProps<HTMLTableSectionElement>` | - | Additional props to spread to the thead element |

### TableBody

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS class names |
| `children` | `React.ReactNode` | - | Body rows |
| `...props` | `React.HTMLProps<HTMLTableSectionElement>` | - | Additional props to spread to the tbody element |

### TableFooter

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS class names |
| `children` | `React.ReactNode` | - | Footer rows |
| `...props` | `React.HTMLProps<HTMLTableSectionElement>` | - | Additional props to spread to the tfoot element |

### TableRow

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS class names |
| `children` | `React.ReactNode` | - | Row cells (`TableHead` or `TableCell`) |
| `...props` | `React.HTMLProps<HTMLTableRowElement>` | - | Additional props to spread to the tr element |

### TableHead

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `scope` | `string` | `'col'` | HTML `scope` attribute for accessibility |
| `className` | `string` | - | Additional CSS class names |
| `children` | `React.ReactNode` | - | Header cell content |
| `...props` | `React.ThHTMLAttributes<HTMLTableCellElement>` | - | Additional props to spread to the th element |

### TableCell

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS class names |
| `children` | `React.ReactNode` | - | Cell content |
| `...props` | `React.TdHTMLAttributes<HTMLTableCellElement>` | - | Additional props to spread to the td element |

### TableCaption

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS class names |
| `children` | `React.ReactNode` | - | Caption text |
| `...props` | `React.HTMLProps<HTMLTableCaptionElement>` | - | Additional props to spread to the caption element |

### MotionTable

`scaleIn` entrance with `springBouncy` transition on mount. Requires the `motion` package.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `...props` | `TableProps` | - | All props from `Table` are supported |

### MotionTableRow

Staggered `scaleIn` entrance with `springBouncy` transition. Requires the `motion` package.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `index` | `number` | `0` | Stagger delay index (50ms per index) for entrance animation |
| `...props` | `TableRowProps` | - | All props from `TableRow` are supported |