@ef2/store-locator NPM

📍 Store Locator

A fully customizable Google Maps Store Locator built for Next.js and React. Supports:
✅ Custom Components (List, Map, Markers, Panels)
✅ Dynamic Clustering with customizable colors
✅ Context & Hooks for extending behavior
✅ TypeScript Support for full type safety
✅ Next.js App Router (SSR-Compatible)

🚀 Installation

npm install @ef2/store-locator
# or
yarn add @ef2/store-locator

🛠️ Basic Usage

Import and use the StoreLocator component in your Next.js App Router.

import { StoreLocator } from "@ef2/store-locator";
import locationsData from "../public/data.json";

const formattedLocations = locationsData.map((location) => ({
	position: { lat: location.position.lat, lng: location.position.lng },
	slug: location.slug || "",
	name: location.name || "",
	city: location.city || "",
	postalCode: location.postalCode || "",
	street: location.street || "",
	phone: location.phone || "",
	email: location.email || "",
	image: location.image || "",
}));

export default function Page() {
	return (
		<StoreLocator
			translations={{
				panelTitle: "In de buurt",
				locationQuantity: "locatie",
				locationQuantity_plural: "locaties",
				placeholder: "Zoek op een plaats",
			}}
			mapOptions={{
				defaultZoom: 8,
				defaultCenter: { lat: 52.370216, lng: 4.895168 },
				mapStyle: {
					mapTypeId: "roadmap",
					renderingType: "RASTER",
					mapId: "71c741f5368dc7b2",
				},
			}}
			apiKey={process.env.NEXT_PUBLIC_GOOGLE_MAPS_API_KEY || ""}
			locations={formattedLocations}
			cluster={{
				fillColor: "#000",
				fillOpacity: 0.7,
				strokeWeight: 2,
				strokeColor: "#ffffff",
				textColor: "#000000",
			}}
		/>
	);
}

🎨 Customizing Components

Every part of the StoreLocator component can be overridden using the components prop.

Example: Override the `List` Component

import CustomList from "./CustomList";

export default function Page() {
	return (
		<StoreLocator
			locations={formattedLocations}
			components={{
				List: CustomList, // ✅ Use custom list component
			}}
		/>
	);
}

Example: Override the `SelectedLocation` Component

import SelectedLocationTest from "./SelectedLocationTest";

export default function Page() {
	return (
		<StoreLocator
			locations={formattedLocations}
			components={{
				SelectedLocation: SelectedLocationTest, // ✅ Custom selected location UI
			}}
		/>
	);
}

📦 Component Structure

StoreLocator is modular, meaning you can swap components as needed.

Component	Description
`StoreLocator`	The main component, includes map, panel, and controls.
`Map`	Renders the Google Map.
`Marker`	Customizable store location markers.
`Markers`	Wrapper for all markers, supports clustering.
`Panel`	Sidebar for location results.
`List`	Displays locations in a list view.
`PanelTop`	The top section of the panel with search/autocomplete.
`SelectedLocation`	The UI shown when a location is selected.

🌍 Multi-Language Support

<StoreLocator
	translations={{
		panelTitle: "Near You",
		locationQuantity: "location",
		locationQuantity_plural: "locations",
		placeholder: "Search for a place",
	}}
/>

🚀 Performance Optimizations

✅ Tree-shakable – Only the components you use are included.
✅ Lazy-loaded Google Maps – Ensures fast page load times.
✅ Uses Context for global state – No unnecessary re-renders.

📦 Importing Individual Hooks & Components

import { useStoreLocator, useStoreLocatorContext } from "@ef2/store-locator/hooks";
import { StoreLocatorProvider } from "@ef2/store-locator/contexts";
import { Location } from "@ef2/store-locator/types";