Skip to Content

ComparisonSection

Compare plans, products, or options with responsive cards or an accessible, keyboard-scrollable feature table.

ComparisonSection compares consumer-provided options and feature values. Each option has a stable ID and title; each feature has an ID, label, and values keyed by option ID.

Beta API maturity: Beta.

Installation

import {
  ComparisonSection,
  type ComparisonFeature,
  type ComparisonOption,
} from "@puzzle-ui/pieces";

Variant previews

Table variants use semantic row/column headers and boolean values are labeled as included or not included. The interactive variant exposes a native radio group. On narrow screens the table scrolls within a labeled, keyboard-focusable viewport rather than widening the page.

table - Compare structured features across a few options.

390 × 844

cards - Compare options as self-contained cards.

390 × 844

split - Emphasize two choices in a side-by-side layout.

390 × 844

versus - Present a direct two-option comparison.

390 × 844

checklist - Scan included and excluded features.

390 × 844

feature-matrix - Compare many features in a semantic table.

390 × 844

pricing - Compare plan features and consumer-provided actions.

390 × 844

highlighted - Draw attention to a recommended option.

390 × 844

horizontal - Lay options out in a responsive row of cards.

390 × 844

vertical - Stack choices for narrow or mobile layouts.

390 × 844

compact - Use a denser presentation for short comparisons.

390 × 844

interactive - Let visitors select an option and compare its values.

390 × 844

API

PropTypeDescription
variantComparisonVariantSelects one of twelve comparison compositions; defaults to table.
optionsreadonly ComparisonOption[]Options with stable id, required title, and optional description/action.
featuresreadonly ComparisonFeature[]Rows with stable id, label, and a values record keyed by option ID.
highlightedOptionIdstringOption emphasized in supported layouts.
comparisonLabelstringAccessible label for the table viewport and table caption.
selectedOptionIdstringControlled selection for variant="interactive".
defaultSelectedOptionIdstringInitial uncontrolled selection for variant="interactive".
onSelectionChange(optionId: string) => voidSelection callback for variant="interactive".
Shared section propsSectionRootProps and heading propsSemantic root, theme, native attributes, heading, actions, and children.

Feature values may be booleans, strings, numbers, or React nodes. Undefined values render as Not provided. Selection state remains local unless controlled; no pricing or billing logic is included.

Usage

<ComparisonSection
  variant="interactive"
  title="Choose a plan"
  options={[
    { id: "starter", title: "Starter" },
    { id: "team", title: "Team", featured: true },
  ]}
  features={[
    { id: "seats", label: "Team members", values: { starter: 3, team: 20 } },
    { id: "support", label: "Priority support", values: { starter: false, team: true } },
  ]}
  defaultSelectedOptionId="starter"
/>

An empty option collection omits the comparison structure. Use unique option and feature IDs, and ensure each feature's value keys match the option IDs.

Accessibility

Tables include a caption, column headers, and row headers. Interactive table options use native radio controls. The scroll viewport is keyboard focusable and labeled so users can reach off-screen columns without page-level horizontal overflow.