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.
horizontal - Browse plans in a horizontal rail.
comparison - Compare plan details in aligned columns.
toggle - Switch between consumer-supplied billing prices.
table - Use a semantic table for detailed comparison.
featured - Emphasize the plan marked as highlighted.
compact - Fit shorter plan summaries into less space.
split - Set a featured plan apart from supporting plans.
enterprise - Make customer-supplied custom pricing prominent.
usage-based - Show customer-provided usage terms beside plan details.
subscription - Make a supplied subscription interval easy to scan.
tiered - Arrange plans as progressive tiers.
minimal - Use a restrained, low-chrome pricing layout.
slider - Pair plans with an optional usage slider.
calculator - Render an estimate only when you provide its function.
API
| Prop | Type | Description |
|---|---|---|
variant | PricingVariant | Selects one of fifteen compositions; defaults to cards. |
plans | readonly PricingPlan[] | Plan data with stable id and name. |
PricingPlan.prices | readonly PricingPlanPrice[] | Supplied values, optional interval ID, currency, interval label, original amount, and discount content. |
PricingPlan.features | readonly PricingFeature[] | Feature rows with a stable ID, label, and optional inclusion/value data. |
PricingPlan.customPricing | ReactNode | Consumer-provided custom-price content, such as a contact link. |
PricingPlan.usage | ReactNode | Optional usage-based terms or explanation. |
PricingPlan.highlighted | boolean | Marks the plan for featured layouts. |
PricingPlan.cta | ReactNode | Optional plan-specific action. |
billingIntervals | readonly PricingBillingInterval[] | Optional labeled choices with unique IDs. More than one choice renders a native radio group. |
billingInterval | string | Controlled selected interval ID. |
defaultBillingInterval | string | Initial interval for uncontrolled use. |
onBillingIntervalChange | (intervalId: string) => void | Notifies the consumer when an interval changes. |
calculator | PricingCalculator | Optional 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.
| Prop | Required | Default |
|---|---|---|
variant | No | "cards" |
plans | Yes | — |
billingIntervals | No | empty array |
billingInterval | No | — |
defaultBillingInterval | No | — |
onBillingIntervalChange | No | — |
calculator | No | — |
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.