@creative-locator/vue

Vue 3 component bindings for Creative Locator.

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

• <DealerLocator /> component — drop a single tag into your template, pass an api-url, render. The component derives the host container from a Vue ref so you never have to manage document.querySelector calls or worry about hydration timing.
• Composition API composables — useDealerLocator / useDealerLocatorState / useDealerEvents give templates reactive access to locator state and typed event subscription with onScopeDispose-driven teardown. See ADR-010 for the design.

Install

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

vue is a peer dependency (^3.4). The package does not bundle Vue.

Usage

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

<template>
	<DealerLocator
		api-url="https://example.com/wp-json/creative-locator/v1"
		:style="{ height: '600px' }"
	/>
</template>

The component renders a single <div> as the host element. Sizing is the host application's responsibility — apply height via the style binding, a 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). Vue's attribute-fallthrough behavior means class, style, id, and other HTML attributes are automatically applied to the root <div>.

| Prop | Type | Default | Notes | | ------------------------- | ---------------------------------- | -------- | ----------------------------------------- | | api-url | string | — | Required. Creative Locator REST base URL. | | config | Partial<LocatorConfig> | {} | Merged over defaultLocatorConfig. | | api-headers | 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. | | enable-google-analytics | boolean | false | GA bridge off by default in headless. | | license-tier | 'free' \| 'pro' | 'free' | Gates Pro layouts client-side. | | adapters | Partial<PlatformAdapters> | — | Per-slot adapter overrides (advanced). |

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 api-url or config does NOT recreate the locator. If you need to swap configuration at runtime, remount via Vue's :key binding:

<template>
	<DealerLocator :key="apiUrl" :api-url="apiUrl" />
</template>

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

Composition API composables

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 the template), use the three composables.

useDealerLocator(containerRef, options)

Mount a locator into a template ref. Returns { locator } — a ShallowRef<DealerLocator | null> that's null before onMounted fires and immediately after the effect scope disposes.

<script setup lang="ts">
import { ref } from 'vue';
import { useDealerLocator } from '@creative-locator/vue';
import '@creative-locator/core/styles/style.scss';

const root = ref<HTMLDivElement | null>(null);
const { locator } = useDealerLocator(root, {
	apiUrl: 'https://example.com/wp-json/creative-locator/v1',
	config: { layout: 'classic' },
});
</script>

<template>
	<div ref="root" style="height: 600px" />
</template>

Teardown registers via onScopeDispose, so the composable works correctly inside components, manual effectScope() blocks, Pinia store factories, and Vue Router navigation guards. The same mount-once contract as the <DealerLocator /> component applies — to swap apiUrl / config at runtime, remount the parent via :key.

useDealerLocatorState(locator)

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

<script setup lang="ts">
import { ref } from 'vue';
import { useDealerLocator, useDealerLocatorState } from '@creative-locator/vue';

const root = ref<HTMLDivElement | null>(null);
const { locator } = useDealerLocator(root, { apiUrl: '...' });
const { allDealers, currentRadius, isViewportMode, currentFilters } =
	useDealerLocatorState(locator);
</script>

<template>
	<div ref="root" />
	<p>Showing {{ allDealers.length }} dealers within {{ currentRadius }} mi.</p>
	<p v-if="isViewportMode">Pan the map to load more.</p>
</template>

Each returned ref is auto-updated after every results:updated / filter:changed / search:start event tick. allDealers and currentFilters are ShallowRefs (the array / object reference is swapped on every change — Vue's deep proxy isn't needed). currentRadius and isViewportMode are regular primitive Refs.

useDealerEvents(locator, 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 setup lang="ts">
import { ref } from 'vue';
import { useDealerLocator, useDealerEvents } from '@creative-locator/vue';

const root = ref<HTMLDivElement | null>(null);
const { locator } = useDealerLocator(root, { apiUrl: '...' });

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

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

The subscription is released on scope dispose, when the locator ref flips to null, and when the locator ref is reassigned to a different instance.

Nuxt

The component touches window and document (via Leaflet), so it must run on the client. In Nuxt 3, wrap it in a <ClientOnly> boundary or use the .client.vue filename suffix:

<!-- components/Locator.client.vue -->
<script setup lang="ts">
import { DealerLocator } from '@creative-locator/vue';
import '@creative-locator/core/styles/style.scss';
</script>

<template>
	<DealerLocator :api-url="$config.public.locatorApiUrl" :style="{ height: '600px' }" />
</template>

License

GPL-2.0-or-later