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.
Variants and location selection
map - Place an app-provided map beside location details.
split - Balance office details with a map or image slot.
cards - Show multiple venues as responsive cards.
offices - List branch offices and their contacts.
single - Focus on one address and its contact details.
directions - Emphasize directions links and coordinates.
image - Pair a location with a caller-provided photograph.
gallery - Arrange several image-led locations.
hours - Highlight weekly opening hours.
interactive - Select a location and update its detail panel.
| Variant | Use case |
|---|---|
map | Put an application map beside address details. |
split | Pair location information with a map or image. |
cards | Compare venues in a responsive card layout. |
offices | Present several branches or offices. |
single | Focus on one location. |
directions | Emphasize directions and coordinates. |
image | Use a caller-provided venue image. |
gallery | Show image-led locations. |
hours | Highlight weekly opening hours. |
interactive | Select a location and update its details. |
Accessibility and responsive behavior
- Location choices are native buttons with
aria-pressedselection state. - Contact values become
tel:andmailto: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
| Prop | Type | Required | Default | Description |
|---|---|---|---|---|
locations | readonly LocationItem[] | Yes | — | Location data; IDs must be unique. |
variant | LocationSectionVariant | No | split | Layout variant. |
selectedLocationId | string | No | — | Controlled selected location. |
defaultSelectedLocationId | string | No | First location | Initial uncontrolled selection. |
onLocationSelect | (id: string) => void | No | — | Called after selection. |
mapSlot | ReactNode | No | Per-item map slot | Caller-provided map content. |
mapLabel | string | No | "Location map" | Accessible map region name. |
className | string | No | — | Additional root class. |
LocationItem supports id, name, address, phone, email, coordinates (latitude, longitude), openingHours (day, hours), directionsHref, image, mapSlot, and description.
Related components
- Contact Section for department and contact forms.
- About Section for organization details.
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.