Mapbox Store Locator Patterns

Store Locator Patterns Skill

Comprehensive patterns for building store locators, restaurant finders, and location-based search applications with Mapbox GL JS. Covers marker display, filtering, distance calculation, interactive lists, and directions integration.

When to Use This Skill

Use this skill when building applications that:

• Display multiple locations on a map (stores, restaurants, offices, etc.)
• Allow users to filter or search locations
• Calculate distances from user location
• Provide interactive lists synced with map markers
• Show location details in popups or side panels
• Integrate directions to selected locations

Dependencies

Required:

• Mapbox GL JS v3.x
• @turf/turf (opens in a new tab) - For spatial calculations (distance, area, etc.)

Installation:

npm install mapbox-gl @turf/turf

Core Architecture

Pattern Overview

A typical store locator consists of:

1. Map Display - Shows all locations as markers
2. Location Data - GeoJSON with store/location information
3. Interactive List - Side panel listing all locations
4. Filtering - Search, category filters, distance filters
5. Detail View - Popup or panel with location details
6. User Location - Geolocation for distance calculation. For the blue dot location indicator, use the built-in mapboxgl.GeolocateControl — simpler than custom markers.
7. Directions - Route to selected location (optional)

Data Structure

GeoJSON format for locations:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [-77.034084, 38.909671]
      },
      "properties": {
        "id": 

Key properties:

• id - Unique identifier for each location
• name - Display name
• address - Full address for display and geocoding
• coordinates - [longitude, latitude] format
• category - For filtering (retail, restaurant, office, etc.)
• Custom properties as needed (hours, phone, website, etc.)

Basic Store Locator Implementation

Step 1: Initialize Map and Data

import mapboxgl from 'mapbox-gl';
import 'mapbox-gl/dist/mapbox-gl.css';

mapboxgl.accessToken = 'YOUR_MAPBOX_ACCESS_TOKEN';

// Store locations data
const stores = {
  type: 'FeatureCollection',
  features: [
    {
      type: 'Feature',

Step 2: Add Markers to Map

Marker strategy by location count:

HTML Markers create one DOM element per point. Beyond ~100 locations the browser spends too much time on layout/paint. Symbol layers bypass the DOM entirely — the GPU draws all points in a single WebGL draw call.

Symbol Layer implementation (best for 100–1,000 locations). For HTML Markers (fewer than 100) or Clustering (more than 1,000), see references/markers.md.

map.on('load', () => {
  // Add store data as source
  map.addSource('stores', {
    type: 'geojson',
    data: stores
  });

Step 3: Build Interactive Location List

function buildLocationList(stores) {
  const listingContainer = document.

Reference Files

Load these references for additional patterns as needed:

Resources

• Turf.js (opens in a new tab) - Spatial analysis library (recommended for distance calculations)
• Mapbox GL JS API (opens in a new tab)
• Interactions API Guide (opens in a new tab)
• GeoJSON Specification (opens in a new tab)
• Directions API (opens in a new tab)
• Store Locator Tutorial