@creative-locator/svelte

Svelte 5 component bindings for Creative Locator.

A thin wrapper around @creative-locator/headless that gives Svelte applications two integration shapes:

• <DealerLocator /> component — drop a single tag into your markup, pass an apiUrl, render. The component derives the host container from a Svelte ref via bind:this so you never have to manage document.querySelector calls or worry about hydration timing.
• Runes factories — createDealerLocator / createDealerLocatorState / createDealerEvent give component <script> blocks $state-backed reactive access to locator state and typed event subscription with $effect-driven teardown. See ADR-010 for the design.

Install

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

svelte is a peer dependency (^5). The package does not bundle Svelte. Svelte 4 is not supported — the component uses Svelte 5 runes ($props / $effect).

Usage

<script lang="ts">
	import { DealerLocator } from '@creative-locator/svelte';
	import '@creative-locator/core/styles/style.scss';
</script>

<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, the class prop, 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 via bind:this), plus two layout-shaped props for the wrapping <div>:

| Prop | Type | Default | Notes | | ----------------------- | ---------------------------------- | -------- | ----------------------------------------- | | apiUrl | string | — | Required. Creative Locator REST base URL. | | config | Partial<LocatorConfig> | {} | Merged over defaultLocatorConfig. | | apiHeaders | Record<string, string> | — | Auth / nonce headers. | | fetch | typeof globalThis.fetch | global | Override for SSR or test contexts. | | storage | 'browser' \| 'memory' \| Storage | auto | Auto-detects SSR. | | enableGoogleAnalytics | boolean | false | GA bridge off by default in headless. | | licenseTier | 'free' \| 'pro' | 'free' | Gates Pro layouts client-side. | | adapters | Partial<PlatformAdapters> | — | Per-slot adapter overrides (advanced). | | class | string | — | Applied to the wrapping <div>. | | style | string | — | Applied to 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 via Svelte's {#key} block:

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

This is the same trade-off Leaflet wrappers (e.g. svelte-leaflet) make for the same reason.

Runes factories

For applications that want reactive bindings into locator state (e.g. rendering a result count, a filter summary, or a "pan map to load more" banner in markup), use the three runes factories. They live in .svelte.ts files and must be called from a Svelte 5 component's <script> block so the $state / $effect runes resolve in a valid reactive scope.

createDealerLocator(containerAccessor, options)

Mount a locator inside a component scope. Returns { locator } — a $state-backed getter that's null before mount and the DealerLocator instance immediately after the container resolves.

<script lang="ts">
	import { createDealerLocator } from '@creative-locator/svelte';
	import '@creative-locator/core/styles/style.scss';

	let container = $state<HTMLDivElement | undefined>();
	const handle = createDealerLocator(() => container, {
		apiUrl: 'https://example.com/wp-json/creative-locator/v1',
		config: { layout: 'classic' },
	});
</script>

<div bind:this={container} style="height: 600px"></div>

The factory's $effect cleanup runs on owner destroy, releasing the locator's destroy() and resetting the rune-backed reference to null. The same mount-once contract as the <DealerLocator /> component applies — to swap apiUrl / config at runtime, remount via {#key}.

createDealerLocatorState(locatorAccessor)

Reactive bridge to the four orchestration-relevant locator state fields:

<script lang="ts">
	import { createDealerLocator, createDealerLocatorState } from '@creative-locator/svelte';

	let container = $state<HTMLDivElement | undefined>();
	const handle = createDealerLocator(() => container, { apiUrl: '...' });
	const state = createDealerLocatorState(() => handle.locator);
</script>

<div bind:this={container} style="height: 600px"></div>
<p>
	Showing {state.allDealers.length} dealers within {state.currentRadius} mi.
</p>
{#if state.isViewportMode}
	<p>Pan the map to load more.</p>
{/if}

Each returned getter is a $state-backed reactive cell — reads in templates, $derived blocks, and other $effect blocks participate in the reactive graph. The factory subscribes to results:updated / filter:changed / search:start and re-reads the snapshot from DealerLocator.getStateSnapshot() on each tick.

createDealerEvent(locatorAccessor, event, handler)

Typed event subscription with automatic teardown. The event parameter is constrained to one of the 10 documented public event slugs; the handler payload type is narrowed automatically with no cast:

<script lang="ts">
	import { createDealerLocator, createDealerEvent } from '@creative-locator/svelte';

	let container = $state<HTMLDivElement | undefined>();
	const handle = createDealerLocator(() => container, { apiUrl: '...' });

	createDealerEvent(() => handle.locator, 'marker:click', (payload) => {
		// `payload` is typed { location: DealerSummary }
		console.log('clicked', payload.location.id);
	});

	createDealerEvent(() => handle.locator, 'results:updated', ({ results, radius }) => {
		// `results` is DealerSummary[], `radius` is number
	});
</script>

<div bind:this={container}></div>

The subscription is released on owner destroy, when the locator accessor returns null, and when the locator accessor swaps to a different instance.

SvelteKit

The component touches window and document (via Leaflet), so it must run on the client. In SvelteKit, gate it behind browser from $app/environment or use onMount:

<script lang="ts">
	import { browser } from '$app/environment';
	import { DealerLocator } from '@creative-locator/svelte';
	import '@creative-locator/core/styles/style.scss';
</script>

{#if browser}
	<DealerLocator
		apiUrl="https://example.com/wp-json/creative-locator/v1"
		style="height: 600px"
	/>
{/if}

Alternatively disable SSR for the page by exporting export const ssr = false from +page.ts.

License

GPL-2.0-or-later