# Comparison Table

- Page: <https://kznlabs.github.io/labsUI/components/comparison-table>

## Comparison Table (`comparison-table`, block)

Products, laptops, plans or ranks compared feature by feature, in groups, with a "differences only" switch. Checks and dashes carry text for screen readers. Wide, every item is a column, the names stay pinned at the top and the features at the left. Narrow, two pickers choose the items side by side and differences follow the two in view.

- Install: `npx @kznlabs/labsui add comparison-table`
- Docs: <https://kznlabs.github.io/labsUI/components/comparison-table>
- Brings: aspect-ratio, badge, field, form-value, input, label, link, list, overflow-focus, platform, select, switch, table, use-anchor, use-controllable-state, use-dismiss, utils
- npm: clsx@^2.1.1, lucide-react@1.63.0, motion@14.7.1, tailwind-merge@^3.7.0

### API

- `<ComparisonTable>` (+ <div> props): A feature-by-feature comparison, grouped, that can show only the differences. Wide, every item is
a column under a pinned header and beside a pinned feature column. Narrow, two pickers choose the
items side by side, each feature's name above its values, and differences follow the two in view.
  - `groups: ComparisonGroup[]`: Grouped rows in display order.
  - `items: ComparisonItem[]`: Columns in display order.
  - `columnLabel?: string` = `"Column"`: Names the column pickers on a narrow screen, before the column's number.
  - `countLabel?: (shown: number, total: number) => string` = `(shown, total) => `${shown} of ${total} rows``: Text beside the switch while it is on. Call it from a client parent to translate.
  - `defaultDifferencesOnly?: boolean` = `false`: "Differences only" at first render (uncontrolled).
  - `differencesLabel?: string` = `"Differences only"`: Text on the switch.
  - `differencesOnly?: boolean`: Controlled "differences only"; pair with `onDifferencesOnlyChange`.
  - `differencesToggle?: boolean` = `true`: Shows the switch. Turn it off for a short table, or when your own control sets `differencesOnly`.
  - `emptyLabel?: ReactNode` = `"Every row is the same."`: Shown when every row is the same.
  - `featureLabel?: string` = `"Feature"`: Read by screen readers as the heading of the feature column.
  - `label?: string` = `"Comparison"`: Names the table for screen readers.
  - `noLabel?: string` = `"No"`: Read by screen readers on a dash.
  - `onDifferencesOnlyChange?: (differencesOnly: boolean) => void`: Called with the new "differences only" state.
  - `stickyTop?: string` = `"0px"`: How far below the top of the page the header pins, as a CSS length. Pass your sticky site header's height.
  - `yesLabel?: string` = `"Yes"`: Read by screen readers on a check.

- `type ComparisonItem = { id: string; name: string; href?: string; media?: ReactNode; details?: ReactNode; action?: ReactNode; badge?: string; featured?: boolean; }`
- `type ComparisonGroup = { label: string; rows: ComparisonRow[]; }`

### Usage

```tsx
<ComparisonTable items={[{ id: "air", name: "Air" }, { id: "pro", name: "Pro", badge: "Popular", featured: true }]} groups={[{ label: "Display", rows: [{ label: "Size", values: { air: "13 in", pro: "16 in" } }, { label: "Touch", values: { air: false, pro: true } }] }]} stickyTop="3.5rem" />
```

### Example: laptops.tsx

```tsx
import { ComparisonTable } from "@/components/blocks/comparison-table";
import { buttonVariants } from "@/components/ui/button-variants";

export function Laptops() {
  return (
    <ComparisonTable
      label="Laptops compared"
      stickyTop="3.5rem"
      items={[
        { id: "lumen", name: "Lumen 13", details: "$899" },
        {
          id: "harbor",
          name: "Harbor 15",
          details: "$1,399",
          badge: "Popular",
          featured: true,
          action: <a className={buttonVariants({ size: "sm" })} href="/buy/harbor">Buy</a>,
        },
      ]}
      groups={[
        {
          label: "Display",
          rows: [
            { label: "Size", values: { lumen: "13.3 in", harbor: "15.6 in" } },
            { label: "Touch screen", values: { lumen: false, harbor: true } },
          ],
        },
        {
          label: "Ports",
          rows: [{ label: "USB-C", values: { lumen: 2, harbor: 2 } }],
        },
      ]}
    />
  );
}
```

### Example: own-cells.tsx

```tsx
import { ComparisonTable } from "@/components/blocks/comparison-table";
import { Badge } from "@/components/ui/badge";

// Your own nodes can't be compared, so say whether the row differs.
export function Support() {
  return (
    <ComparisonTable
      items={[
        { id: "iron", name: "Iron" },
        { id: "gold", name: "Gold" },
      ]}
      groups={[
        {
          label: "Support",
          rows: [
            {
              label: "Reply within",
              differs: true,
              values: { iron: <Badge variant="secondary">48 h</Badge>, gold: <Badge>4 h</Badge> },
            },
          ],
        },
      ]}
    />
  );
}
```
