Booking Section
Compose booking dates, availability, pricing, and form submission without a booking or payment backend.
BookingSection arranges caller-provided booking details, calendar, availability, form fields, and price summary. It does not calculate inventory, reserve a slot, charge a customer, or call a backend.
Beta API maturity: Beta.
Import
import { BookingSection, type BookingStep } from "@puzzle-ui/pieces";Basic usage
Use the existing UI DatePicker or another calendar in the calendar slot. The formSlot contains controls; the section wraps them in a form only when onSubmit is provided.
Variants
calendar - Let the application provide a calendar picker.
form - Keep guest details and submission together.
split - Separate booking details from the form.
availability - Present availability supplied by the app.
appointment - Collect an appointment request.
event - Collect an event or session reservation.
accommodation - Summarize a hotel stay and dates.
restaurant - Collect a dining date and party size.
multi-step - Show caller-owned progress through booking steps.
sidebar - Keep the price summary beside the booking form.
compact - Fit a shorter booking panel into a small space.
| Variant | Use case |
|---|---|
calendar | Put a date picker first. |
form | Focus on a booking form. |
split | Divide form and supporting details. |
availability | Highlight application-provided availability. |
appointment | Request an appointment. |
event | Collect event reservations. |
accommodation | Present a stay with dates and price summary. |
restaurant | Collect a dining date and party size. |
multi-step | Show a caller-controlled booking flow. |
sidebar | Keep a price summary beside the main form. |
compact | Use a denser booking panel. |
Interactive booking flow
The current step and availability remain app-owned. BookingStep.completed drives the displayed progress; onStepChange reports requested navigation without persisting or validating business state.
onSubmit receives a native FormData object from the wrapped form. Async callbacks expose loading, success, and error states. The component shows the error message returned by a rejected Error, or a generic failure message for other thrown values.
Accessibility and responsive behavior
- The calendar should have a visible label; UI
DatePickersupports keyboard operation and native form integration. - Step state uses an ordered list,
aria-current="step", and a named progressbar. - Native form validation, labels, and keyboard submission are preserved.
- Loading sets
aria-busy, disables the submit action, and announces status/error updates. - Split and sidebar layouts collapse to one column on narrow screens.
API
| Prop | Type | Required | Default | Description |
|---|---|---|---|---|
variant | BookingSectionVariant | No | form | Layout variant. |
bookingDetails | ReactNode | No | — | Booking summary slot. |
calendar | ReactNode | No | — | Calendar/date-picker slot. |
availability | ReactNode | No | — | App-provided availability presentation. |
formSlot | ReactNode | No | — | Form controls; do not nest a second <form> when using onSubmit. |
priceSummary | ReactNode | No | — | Caller-provided price breakdown. |
steps | readonly BookingStep[] | No | [] | Optional visual multi-step flow. |
currentStepId | string | No | — | Current step. |
onStepChange | (id: string) => void | No | — | Called when a step is selected. |
onSubmit | (formData: FormData) => void | Promise<void> | No | — | Submit callback; no network request is performed. |
submitLabel | ReactNode | No | "Confirm booking" | Submit button label. |
loading | boolean | No | false | External loading state. |
success, error | ReactNode | No | — | Optional caller-provided status content. |
Related components
- Settings for application-owned form settings.
- Date Picker for calendar selection.
- Price components for commerce summaries.
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 { BookingSection } from "@puzzle-ui/pieces";
type BookingSectionProps = ComponentProps<typeof BookingSection>;
export function CustomizedSection(props: BookingSectionProps) {
return (
<BookingSection
{...props}
className={[props.className, "brand-section"].filter(Boolean).join(" ")}
/>
);
}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 { BookingSection } from "@puzzle-ui/pieces";
type BookingSectionProps = ComponentProps<typeof BookingSection>;
export function SectionWrapper(props: BookingSectionProps) {
return <BookingSection {...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.