Skip to Content

AvailabilitySearchSection

Present an accessible accommodation search form with caller-owned dates, guest counts, validation, and external availability actions.

AvailabilitySearchSection presents check-in and check-out dates, guest counts, optional child ages, an optional accommodation choice, and flexible-date preferences. It does not check inventory, calculate availability, or contact a service.

Beta API maturity: Beta.

TypeScript example

import {
  AvailabilitySearchSection,
  type AvailabilitySearchValues,
} from "@puzzle-ui/pieces";

Compact and expanded variants

Compact search keeps the form dense; expanded search gives the fields more space. Both variants retain the same fields and validation behavior.

compact - Keep date and guest search controls concise.

390 × 844

expanded - Give search fields more room in a dedicated search area.

390 × 844

The submit callback receives values after local date and guest validation; the application decides whether and how to query an external provider.

Controlled state

Pass the complete AvailabilitySearchValues object to control dates, guests, the selected accommodation, and flexible-date state. onChange reports the next complete object.

390 × 844
390 × 844

External loading and errors

The component shows its own pending state while an async onSubmit callback is running. Pass loading and error when the surrounding application owns those states, or use errors to connect application validation to individual fields.

390 × 844

API

PropTypeRequiredDefaultDescription
variant"compact" | "expanded"No"compact"Controls field spacing.
valueAvailabilitySearchValuesNo—Complete controlled search value.
defaultValueAvailabilitySearchInitialValueNoDates unset, 2 adults, 0 children, no accommodation, inflexible datesInitial uncontrolled value; guest fields can be initialized partially.
accommodationsreadonly AvailabilityAccommodationOption[]No[]Options supplied by the application.
childAgeOptionsreadonly AvailabilityChildAgeOption[]No[]Adds one optional age selector per child.
accommodationRequiredbooleanNofalseRequires an option when the search is submitted.
minAdults, maxAdultsnumberNo1, 20Inclusive guest-count bounds.
minChildren, maxChildrennumberNo0, 20Inclusive guest-count bounds.
localestringNoRuntime localeBCP 47 locale forwarded to the date pickers.
dateFormatIntl.DateTimeFormatOptionsNoUI DatePicker defaultDate display options, including an explicit timeZone if needed.
requiredDescriptionReactNodeNo"Required"Accessible required-state description for both date fields; localize as needed.
errorsAvailabilitySearchErrorsNo—Caller-provided per-field errors. These prevent submit until cleared.
errorReactNodeNo—Caller-provided form-level error content.
loadingbooleanNofalseExternal pending state; disables the controls.
disabledbooleanNofalseDisables the controls and submit button.
submitLabel, loadingLabelReactNodeNo"Search availability", "Searching..."Submit button labels.
onChange(value: AvailabilitySearchValues) => voidNo—Receives every updated complete value.
onSubmit(value: AvailabilitySearchValues) => void | Promise<void>Yes—Receives locally valid values; the application provides any availability action.
onValidationError(errors: AvailabilitySearchErrors) => voidNo—Notifies the application when local or supplied field errors prevent submit.

AvailabilitySearchValues contains checkIn and checkOut (Date | null), guests (GuestCount), accommodationId (string | null), and flexibleDates (boolean). GuestCount contains integer adults and children counts plus optional childAges entries (number | null). Child age selectors appear only when childAgeOptions are supplied; age values are not required.

The component rejects invalid configured bounds and duplicate option IDs. On submit, it requires both dates, requires checkout to be on a later calendar day, checks the configured guest bounds, and optionally checks the accommodation choice. It does not assume future-date limits, check actual availability, or validate provider-specific rules.

Integration boundary

All accommodation options, child-age labels, and external errors are supplied through props. The application owns the availability request, provider-specific validation, persistence, route changes, rate lookup, reservations, and payment. Use BookingSection instead when a generic booking layout with caller-provided form slots is a better fit.

Responsive behavior and accessibility

  • The field grid shrinks to one column when the viewport cannot fit its minimum field width; no fixed-width date fields or sticky elements are used.
  • UI DatePicker, Select, NumberInput, Checkbox, and FormField provide the calendar, popover, guest controls, labels, and field error relationships.
  • Check-in and check-out labels are required; errors are associated with their field and the form-level error uses an alert role.
  • The form uses noValidate so the component can report its own date and guest errors consistently without native validation blocking its callback.
  • Use an explicit locale and a matching dateFormat.timeZone when server and client environments need identical date output.

Theme support and customization

The section and controls consume Puzzle Theme tokens and inherit scoped themes. Use the shared title, description, eyebrow, actions, alignment, and className section props to compose it with a page; the form controls remain Puzzle UI components rather than caller-rebuilt inputs.

Use the component in either supported framework; see Framework Integration for Next.js and TanStack Start guidance.