Skip to Content

PricingSection

Compose subscription and usage-based SaaS plans with explicit billing options, accessible comparisons, and optional calculators.

PricingSection renders the pricing and feature values that you provide. It does not derive prices, apply discounts, or calculate estimates unless you supply a calculator renderer.

Beta API maturity: Beta.

Installation

import {
  PricingSection,
  type PricingPlan,
  type PricingBillingInterval,
} from "@puzzle-ui/pieces";

Variant previews

Each pricing layout has its own preview. The fictional plans include explicit monthly and annual values so the billing control can be exercised interactively.

cards - Compare plan cards in a familiar pricing grid.

390 × 844

horizontal - Browse plans in a horizontal rail.

390 × 844

comparison - Compare plan details in aligned columns.

390 × 844

toggle - Switch between consumer-supplied billing prices.

390 × 844

table - Use a semantic table for detailed comparison.

390 × 844

featured - Emphasize the plan marked as highlighted.

390 × 844

compact - Fit shorter plan summaries into less space.

390 × 844

split - Set a featured plan apart from supporting plans.

390 × 844

enterprise - Make customer-supplied custom pricing prominent.

390 × 844

usage-based - Show customer-provided usage terms beside plan details.

390 × 844

subscription - Make a supplied subscription interval easy to scan.

390 × 844

tiered - Arrange plans as progressive tiers.

390 × 844

minimal - Use a restrained, low-chrome pricing layout.

390 × 844

slider - Pair plans with an optional usage slider.

390 × 844

calculator - Render an estimate only when you provide its function.

390 × 844

API

PropTypeDescription
variantPricingVariantSelects one of fifteen compositions; defaults to cards.
plansreadonly PricingPlan[]Plan data with stable id and name.
PricingPlan.pricesreadonly PricingPlanPrice[]Supplied values, optional interval ID, currency, interval label, original amount, and discount content.
PricingPlan.featuresreadonly PricingFeature[]Feature rows with a stable ID, label, and optional inclusion/value data.
PricingPlan.customPricingReactNodeConsumer-provided custom-price content, such as a contact link.
PricingPlan.usageReactNodeOptional usage-based terms or explanation.
PricingPlan.highlightedbooleanMarks the plan for featured layouts.
PricingPlan.ctaReactNodeOptional plan-specific action.
billingIntervalsreadonly PricingBillingInterval[]Optional labeled choices with unique IDs. More than one choice renders a native radio group.
billingIntervalstringControlled selected interval ID.
defaultBillingIntervalstringInitial interval for uncontrolled use.
onBillingIntervalChange(intervalId: string) => voidNotifies the consumer when an interval changes.
calculatorPricingCalculatorOptional labeled range control with a consumer-supplied estimate renderer.

PricingPlanPrice.amount, currency, interval, originalAmount, and discount are presentation values. The table variant renders an accessible table with column and row headers. Empty plan collections render no cards or comparison table.

Required and default values

Requiredness follows the exported TypeScript type. A dash means no component-level default is applied; variant-specific requirements are described in the API table above.

PropRequiredDefault
variantNo"cards"
plansYes—
billingIntervalsNoempty array
billingIntervalNo—
defaultBillingIntervalNo—
onBillingIntervalChangeNo—
calculatorNo—

Usage

const plans: PricingPlan[] = [
  {
    id: "team",
    name: "Team",
    prices: [
      { intervalId: "monthly", currency: "$", amount: 49, interval: "per month" },
      { intervalId: "annual", currency: "$", amount: 490, interval: "per year" },
    ],
    features: [
      { id: "projects", label: "Projects", value: "Unlimited" },
      { id: "support", label: "Priority support", included: true },
    ],
    highlighted: true,
    cta: <a href="/signup">Choose Team</a>,
  },
];

const billingIntervals: PricingBillingInterval[] = [
  { id: "monthly", label: "Monthly" },
  { id: "annual", label: "Annually" },
];

<PricingSection
  variant="toggle"
  title="Choose a plan"
  plans={plans}
  billingIntervals={billingIntervals}
  defaultBillingInterval="monthly"
/>;

Explicit calculator logic

The slider variant presents a compact range control; calculator also renders renderEstimate. The component never supplies calculation logic. This example deliberately supplies its own estimate function:

<PricingSection
  variant="calculator"
  plans={plans}
  calculator={{
    label: "Monthly events",
    min: 1000,
    max: 10000,
    step: 1000,
    initialValue: 3000,
    formatValue: (value) => `${value} events`,
    renderEstimate: (value) => <p>Example estimate: ${(value / 1000) * 8} per month.</p>,
  }}
/>;

Invalid or duplicate billing interval IDs and invalid calculator bounds throw an explicit error. Price conversion and discount math are never inferred from plan data.

Accessibility

Billing choices use a labeled native radio group with keyboard behavior. The comparison table uses a caption and scoped headers, and its horizontal overflow area can receive keyboard focus. Calculator controls use an associated label and output; consumers remain responsible for accessible names and destinations in CTA content.

Customization

Use the component's className and documented slots to adapt the composition. Prefer a caller-provided ReactNode for media, actions, or controls rather than adding domain behavior to the section.

import type { ComponentProps } from "react";
import { PricingSection } from "@puzzle-ui/pieces";

type PricingSectionProps = ComponentProps<typeof PricingSection>;

export function CustomizedSection(props: PricingSectionProps) {
  return <PricingSection {...props} className={[props.className, "brand-section"].filter(Boolean).join(" ")} />;
}

Responsive behavior

Use the preview device selector to review mobile, tablet, and desktop widths. The built-in variant controls section structure; ensure application-provided media, form controls, and children can shrink or wrap without horizontal overflow. Use the existing responsive breakpoints in scoped CSS when the consuming layout needs a product-specific adjustment.

Theme support

The section consumes semantic variables from @puzzle-ui/theme and inherits active or scoped themes. Wrap the application with Theme, and use semantic roles such as text, surface, border, and primary for local overrides. Avoid hard-coded colors, spacing, radii, and shadows.

.brand-section {
  color: var(--puzzle-color-text);
  background: var(--puzzle-color-surface);
  border-color: var(--puzzle-color-border);
}

Composition

Compose this section with the UI primitives named in its API and use the documented slots for consumer-owned controls or media. Keep data fetching, routing, validation, permissions, and persistence in the application. The children slot is intended for additional content that belongs with this section, not as a substitute for its typed data model.

TypeScript example

The package exports this component from its root. Derive a wrapper's exact prop type from the public component rather than widening it:

import type { ComponentProps } from "react";
import { PricingSection } from "@puzzle-ui/pieces";

type PricingSectionProps = ComponentProps<typeof PricingSection>;

export function SectionWrapper(props: PricingSectionProps) {
  return <PricingSection {...props} />;
}

Framework compatibility

The section is router-independent. Static compositions can be server-rendered; place callback-driven interactions in the framework's client boundary. See Next.js and TanStack Start integration for runnable framework examples and SSR guidance.