Skip to Content

Local Guide

Present caller-supplied nearby places and activities with categories, optional distances, travel times, links, and map content.

LocalGuideSection adapts the existing ResourceSection card and category-filter layout for nearby places and activities. It does not geocode locations or calculate distance or travel time.

Beta API maturity: Beta.

Installation

import { LocalGuideSection, type LocalGuideItem } from "@puzzle-ui/pieces";

Variant previews

Grid, list, featured, and category layouts reuse ResourceSection. Links, distances, travel times, and the optional map are supplied by the application.

grid - Browse a balanced list of local places.

390 × 844

list - Give longer descriptions more room.

390 × 844

featured - Lead with a recommended nearby place.

390 × 844

categories - Group places by their supplied category.

390 × 844

Empty state

Explore the area

No resources found

Try a different search or category.

Local recommendations will appear here.

API

PropTypeRequiredDefault
placesreadonly LocalGuideItem[]Yes—
featuredPlaceIdstringNoFirst featured item, otherwise first place, for the featured variant
variantResourceSectionVariantNo"grid"
filterablebooleanNotrue
mapSlotReactNodeNo—
mapLabelstringNo"Local guide map"
distanceLabelReactNodeNo"Distance"
travelTimeLabelReactNodeNo"Travel time"
emptyStateReactNodeNoResourceSection empty state
Shared section propsMarketingSectionBasePropsNo—

LocalGuideItem

FieldTypeRequiredDescription
idstringYesStable item identifier.
titlestringYesPlace or activity name.
descriptionReactNodeNoCaller-provided description.
categorystringNoCategory used by the existing filter.
kindstringNoVisible type label, such as “Walk” or “Market”.
hrefstringNoCaller-provided destination; items without it are not rendered as links.
distanceReactNodeNoSupplied distance text or content.
travelTimeReactNodeNoSupplied travel-time text or content.
thumbnailReactNodeNoOptional caller-rendered media with meaningful alternative text.
featuredbooleanNoMarks an item for the featured layout.

Usage

const places: LocalGuideItem[] = [
  {
    id: "dune-path",
    title: "Dune path",
    description: "A gentle loop through the coastal grassland.",
    kind: "Walk",
    category: "Outdoors",
    distance: "1.2 km",
    travelTime: "15 minutes on foot",
    href: "https://example.test/dune-path",
  },
  {
    id: "market",
    title: "Village market",
    kind: "Market",
    category: "Food",
    distance: "800 m",
  },
];

<LocalGuideSection title="Explore nearby" places={places} />;

Responsive behavior

The card layout and category filter inherit ResourceSection's responsive grid and wrapping behavior. The optional mapSlot is rendered after the list and constrained to its container; provide media that can shrink to the available width.

Accessibility

Entries without an href remain headings rather than fake links. Supply meaningful image alternatives for thumbnails and an accessible name for interactive map content. Category filtering uses the existing native select control.

Theme support

Cards, filters, and empty states inherit ResourceSection's Puzzle theme tokens, including in scoped themes.

Customization

Pass caller-owned map content through mapSlot, and use shared section props and className for heading and layout customization. LocalGuide does not own map rendering, geocoding, or travel calculations.

Composition

Use LocationSection for the venue's own address and contact information. Use LocalGuideSection for nearby places and activities. See the Boutique B&B and Restaurant Experience pages.

TypeScript example

LocalGuideItem and LocalGuideSection are root exports from @puzzle-ui/pieces; no family subpath import is required.

Framework compatibility

The section is router-independent. Category filtering uses React client behavior; server-rendered output is available before hydration. See Next.js and TanStack Start integration.