Skip to Content

AccommodationOverviewSection

Present accommodation options with responsive cards, stay details, prices, highlights, and a focused carousel.

AccommodationOverviewSection presents accommodation data supplied by your application. Cards can show images, guest capacity, bedrooms, beds, bathrooms, price indications, badges, highlights, and a caller-provided action.

Beta API maturity: Beta.

Installation

import {
  AccommodationOverviewSection,
  type AccommodationOverviewItem,
} from "@puzzle-ui/pieces";

Variant previews

Grid and list layouts adapt to the available width. The carousel uses the UI Carousel with one, two, or three visible stays at mobile, tablet, and desktop sizes. Its caret controls sit beside the content and its page indicator appears below it, including when there is only one stay.

grid - Compare stays at a glance.

390 × 844

list - Give more room to descriptions and metadata.

390 × 844

carousel - Focus on a few featured stays in a compact horizontal space.

390 × 844

API

Prop or typeTypeDescription
variantAccommodationOverviewVariantgrid (default), list, or carousel.
itemsreadonly AccommodationOverviewItem[]Accommodation records with unique IDs.
localestringCurrency locale passed to the existing commerce price renderer; defaults to "en-US" for compatibility.
AccommodationOverviewItem.namestringRequired accommodation name.
AccommodationOverviewItem.imageEditorialImageOptional responsive image and alternative text; an empty or missing source is handled by the shared image primitive.
AccommodationOverviewItem.descriptionReactNodeOptional descriptive content.
AccommodationOverviewItem.capacity, bedrooms, beds, bathroomsnumberOptional non-negative safe-integer counts.
AccommodationOverviewItem.priceCommerceMoneyOptional amount and ISO 4217 currency; displayed using the existing Pieces price renderer.
AccommodationOverviewItem.priceNoteReactNodeOptional text such as a stay period or pricing qualifier.
AccommodationOverviewItem.badgesreadonly AccommodationBadge[]Optional badges with stable IDs and caller-provided content.
AccommodationOverviewItem.highlightsreadonly AccommodationFeature[]Optional short features with optional icon and description.
AccommodationOverviewItem.hrefstringNative destination for the name and default “View details” link.
AccommodationOverviewItem.actionReactNodeCustom CTA; takes precedence over the default details link.
AccommodationOverviewItem.featuredbooleanAdds a featured badge and visual emphasis.
Shared section propsMarketingSectionBasePropsSection root, heading, actions, children, theme, and native attributes.

Required and default values

PropRequiredDefault
itemsYes—
variantNo"grid"
localeNo"en-US"

TypeScript example

const stays: AccommodationOverviewItem[] = [
  {
    id: "pinecone-cabin",
    name: "Pinecone Cabin",
    description: "A quiet woodland cabin for two.",
    image: { src: "/stays/pinecone.jpg", alt: "Pinecone Cabin among trees" },
    capacity: 2,
    bedrooms: 0,
    beds: 1,
    bathrooms: 1,
    price: { amount: 125, currency: "EUR" },
    priceNote: "per night",
    href: "/stays/pinecone-cabin",
    featured: true,
  },
];

<AccommodationOverviewSection
  title="Find your place to stay"
  variant="grid"
  items={stays}
/>;

The component validates unique item, badge, and highlight IDs and rejects negative, fractional, or unsafe accommodation counts. price is optional; there is no booking, availability, or payment behavior. If both action and href are supplied, the custom action is rendered instead of the default details link.

Accessibility

Cards use article semantics inside a list, with a heading, descriptive image alternative text, and definition-list metadata. Featured and badge content is textual. Provide a meaningful label for caller-supplied icon-only actions. Carousel controls and keyboard/touch navigation come from the UI package's existing Carousel.

Responsive behavior

The grid uses an auto-fitting fluid layout. List cards stack on narrow viewports and align image and copy side by side when space allows. Images retain a consistent 4:3 ratio without fixed card heights. The carousel shows one, two, or three cards at the UI breakpoints and is omitted for a single item. Long names and descriptions wrap instead of forcing horizontal overflow.

Theme support

Cards and labels consume semantic Puzzle theme tokens and inherit root or scoped themes. No component-specific color palette is introduced.

Customization

Use the shared actions, children, and className section props, or provide an item-level action for a CTA inside its card. The card image, features, and badges accept React content where appropriate.

import { Button } from "@puzzle-ui/ui";

<AccommodationOverviewSection
  items={stays.map((stay) => ({
    ...stay,
    action: <Button href={stay.href}>See this stay</Button>,
  }))}
/>

Composition

Compose this overview with AccommodationDetailsSection, AmenityListSection, the existing AccommodationHero, and GallerySection. The overview does not create a second hero, image gallery, or booking system.

Framework compatibility

The module is a client component to host the existing interactive carousel; its default grid and list output remains server-renderable. It is router-independent and accepts application-owned data. In Next.js App Router and TanStack Start, keep any callback-driven action inside the appropriate client boundary.