Skip to Content

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.

390 × 844

Variants

calendar - Let the application provide a calendar picker.

390 × 844

form - Keep guest details and submission together.

390 × 844

split - Separate booking details from the form.

390 × 844

availability - Present availability supplied by the app.

390 × 844

appointment - Collect an appointment request.

390 × 844

event - Collect an event or session reservation.

390 × 844

accommodation - Summarize a hotel stay and dates.

390 × 844

restaurant - Collect a dining date and party size.

390 × 844

multi-step - Show caller-owned progress through booking steps.

390 × 844

sidebar - Keep the price summary beside the booking form.

390 × 844

compact - Fit a shorter booking panel into a small space.

390 × 844
VariantUse case
calendarPut a date picker first.
formFocus on a booking form.
splitDivide form and supporting details.
availabilityHighlight application-provided availability.
appointmentRequest an appointment.
eventCollect event reservations.
accommodationPresent a stay with dates and price summary.
restaurantCollect a dining date and party size.
multi-stepShow a caller-controlled booking flow.
sidebarKeep a price summary beside the main form.
compactUse 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.

390 × 844

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 DatePicker supports 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

PropTypeRequiredDefaultDescription
variantBookingSectionVariantNoformLayout variant.
bookingDetailsReactNodeNo—Booking summary slot.
calendarReactNodeNo—Calendar/date-picker slot.
availabilityReactNodeNo—App-provided availability presentation.
formSlotReactNodeNo—Form controls; do not nest a second <form> when using onSubmit.
priceSummaryReactNodeNo—Caller-provided price breakdown.
stepsreadonly BookingStep[]No[]Optional visual multi-step flow.
currentStepIdstringNo—Current step.
onStepChange(id: string) => voidNo—Called when a step is selected.
onSubmit(formData: FormData) => void | Promise<void>No—Submit callback; no network request is performed.
submitLabelReactNodeNo"Confirm booking"Submit button label.
loadingbooleanNofalseExternal loading state.
success, errorReactNodeNo—Optional caller-provided status 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 { 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.