@creative-locator/react

React component bindings for Creative Locator.

A thin wrapper around @creative-locator/headless that gives React applications a one-component install: drop a <DealerLocator /> into your JSX, pass an apiUrl, render. The component derives the host container from a ref so you never have to manage document.querySelector calls or worry about hydration timing.

Install

pnpm add @creative-locator/core @creative-locator/headless @creative-locator/react leaflet leaflet.markercluster

react and react-dom are peer dependencies (^18 || ^19). The package does not bundle React.

Usage

import { DealerLocator } from '@creative-locator/react';
import '@creative-locator/core/styles/style.scss';

export function LocatorPage() {
    return (
        <DealerLocator
            apiUrl="https://example.com/wp-json/creative-locator/v1"
            style={{ height: '600px' }}
        />
    );
}

The component renders a single <div> as the host element. Sizing is the host application's responsibility — apply height via the style prop, a CSS class, or a parent container. Without a non-zero height, the locator's map will not be visible.

Props

DealerLocator accepts every option from createHeadlessLocator except container (which is derived from the component's internal ref), plus two layout-shaped props for the wrapping <div>:

See @creative-locator/headless for the canonical option reference.

Mount-once contract

Like most map libraries, the locator is expensive to initialize. The component intentionally ignores prop changes after the initial mount — re-rendering with a new apiUrl or config does NOT recreate the locator. If you need to swap configuration at runtime, remount the component via React's key prop:

<DealerLocator key={apiUrl} apiUrl={apiUrl} />

This is the same trade-off Leaflet wrappers (react-leaflet etc.) make for the same reason.

Hooks (#994 PR A)

Three React hooks expose the underlying DealerLocator for templates that want reactive access to locator state and typed event subscription. The component above is the simplest entry; hooks are the idiomatic shape for richer integrations. See docs/adr/ADR-010-framework-adapter-composables.md for the design.

import { useRef } from 'react';
import { useDealerLocator, useDealerLocatorState, useDealerEvents } from '@creative-locator/react';

export function LocatorPage() {
    const root = useRef<HTMLDivElement | null>(null);
    const { locator } = useDealerLocator(root, { apiUrl: '...' });
    const { allDealers, currentRadius } = useDealerLocatorState(locator);
    useDealerEvents(locator, 'marker:click', ({ location }) => {
        console.log('clicked', location.id);
    });

    return (
        <>
            <div ref={root} style={{ height: 600 }} />
            <p>
                {allDealers.length} dealers within {currentRadius} mi.
            </p>
        </>
    );
}

useDealerLocatorState uses useSyncExternalStore so concurrent-mode React reads a consistent snapshot. The snapshot identity is cached per locator — destructured fields keep referential stability across renders when state hasn't moved.

Next.js 15 App Router (#994 PR B)

The package ships a react-server exports condition. Inside a Server Component, import { DealerLocator } from '@creative-locator/react' resolves to the Server Component entry — an async function that renders the static shell HTML server-side, optionally fetches and inlines the initial dealer payload, and hands off interactivity to a Client Component child on hydration.

// app/locator/page.tsx — runs on the server
import { DealerLocator } from '@creative-locator/react';
import '@creative-locator/core/styles/style.scss';

export default function LocatorPage() {
    return (
        <DealerLocator
            apiUrl="https://example.com/wp-json/creative-locator/v1"
            style={{ height: 600 }}
        />
    );
}

The Server Component issues a fetch(${apiUrl}/dealers?limit=20) itself by default (Next 15's fetch cache + dedupe makes this effectively free) and emits the result as an inline <script type="application/json"> payload that the client-side HydrationOrchestrator.tryHydrateFromInlinePayload() picks up. The user sees dealer markers on first paint, before any REST round-trip resolves on the client.

Pass initialPayload to skip the SC's own fetch when you've already fetched the data upstream:

export default async function LocatorPage() {
    const res = await fetch('https://example.com/wp-json/creative-locator/v1/dealers?limit=50');
    const json = await res.json();
    return (
        <DealerLocator
            apiUrl="https://example.com/wp-json/creative-locator/v1"
            initialPayload={{ dealers: json.dealers, total: json.total }}
            fetchInitialPayload={false}
        />
    );
}

Server Component props

Non-serializable overrides (fetch, adapters) are not exposed here because they can't cross the RSC → Client boundary. Compose your own Client Component if you need them.

Subpath imports (escape hatch)

The react-server condition does the right thing automatically. For cases where you need to bypass the conditional resolution:

• @creative-locator/react/server — always the Server Component.
• @creative-locator/react/client — always the legacy SPA component + hooks.

SPA-only consumers

If you're not on the App Router (e.g. still on Pages Router, CRA, or Vite SPA), the package's default condition resolves to the legacy client-only <DealerLocator /> — the same drop-in wrapper that's been here since #515. Nothing changes for those consumers.

Astro

Use the @astrojs/react integration to render the component as a client island:

---
// src/pages/locator.astro
import { DealerLocator } from '@creative-locator/react';
import '@creative-locator/core/styles/style.scss';
---

<DealerLocator
    client:only="react"
    apiUrl={import.meta.env.PUBLIC_LOCATOR_API_URL}
    style={{ height: '600px' }}
/>

client:only="react" skips SSR entirely (Leaflet needs window).

License

GPL-2.0-or-later