Skip to Content

Location Section

Present offices, hotels, restaurants, contact details, opening hours, and app-provided map content.

LocationSection presents one or more venues with contact information, coordinates, opening hours, direction links, and optional media. The map is a caller-provided slot; no map provider or API key is required.

Beta API maturity: Beta.

Basic usage

Provide a stable ID for each location. When the section has multiple locations, its native buttons manage local selection unless selectedLocationId is supplied as a controlled value.

390 × 844

Variants and location selection

map - Place an app-provided map beside location details.

390 × 844

split - Balance office details with a map or image slot.

390 × 844

cards - Show multiple venues as responsive cards.

390 × 844

offices - List branch offices and their contacts.

390 × 844

single - Focus on one address and its contact details.

390 × 844

directions - Emphasize directions links and coordinates.

390 × 844

image - Pair a location with a caller-provided photograph.

390 × 844

gallery - Arrange several image-led locations.

390 × 844

hours - Highlight weekly opening hours.

390 × 844

interactive - Select a location and update its detail panel.

390 × 844
VariantUse case
mapPut an application map beside address details.
splitPair location information with a map or image.
cardsCompare venues in a responsive card layout.
officesPresent several branches or offices.
singleFocus on one location.
directionsEmphasize directions and coordinates.
imageUse a caller-provided venue image.
galleryShow image-led locations.
hoursHighlight weekly opening hours.
interactiveSelect a location and update its details.
390 × 844

Accessibility and responsive behavior

  • Location choices are native buttons with aria-pressed selection state.
  • Contact values become tel: and mailto: links; directions remain caller-provided.
  • The optional map is a labelled region. If embedding a map or iframe, give its own frame an accessible title and keep a text address available.
  • Layouts adapt from split columns to a single column on mobile.

API

PropTypeRequiredDefaultDescription
locationsreadonly LocationItem[]Yes—Location data; IDs must be unique.
variantLocationSectionVariantNosplitLayout variant.
selectedLocationIdstringNo—Controlled selected location.
defaultSelectedLocationIdstringNoFirst locationInitial uncontrolled selection.
onLocationSelect(id: string) => voidNo—Called after selection.
mapSlotReactNodeNoPer-item map slotCaller-provided map content.
mapLabelstringNo"Location map"Accessible map region name.
classNamestringNo—Additional root class.

LocationItem supports id, name, address, phone, email, coordinates (latitude, longitude), openingHours (day, hours), directionsHref, image, mapSlot, and description.

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 { LocationSection } from "@puzzle-ui/pieces";

type LocationSectionProps = ComponentProps<typeof LocationSection>;

export function CustomizedSection(props: LocationSectionProps) {
  return (
    <LocationSection
      {...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 { LocationSection } from "@puzzle-ui/pieces";

type LocationSectionProps = ComponentProps<typeof LocationSection>;

export function SectionWrapper(props: LocationSectionProps) {
  return <LocationSection {...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.