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

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](https://turfjs.org/) For spatial calculations (distance, area, etc.) Installation: 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: 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 Step 2: Add Markers to Map Marker strategy by location count: Count Strategy Reason Fewer than 100 HTML Markers Full DOM/CSS control; DOM node count is manageable 100–1,000 Symbol Layer (default) Renders on the GPU via WebGL — one <canvas , zero per point DOM elements More than 1,000 Clustering Reduces visual clutter at large scale 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 . Step 3: Build Interactive Location List Reference Files Load these references for additional patterns as needed: Reference File Contents HTML Markers & Clustering references/markers.md HTML Markers (< 100 locations), Clustering ( 1000 locations) Search & Filter references/search filter.md Text search, category filter Geolocation & Directions references/geolocation directions.md User location, distance calculation, route directions Styling & Layout references/styling layout.md Full HTML/CSS layout, custom marker CSS Performance & A11y references/optimization a11y.md Debounced search, data management, error handling, accessibility Variations & React references/variations react.md Mobile first, fullscreen, map only, React implementation Resources [Turf.js](https://turfjs.org/) Spatial analysis library (recommended for distance calculations) [Mapbox GL JS API](https://docs.mapbox.com/mapbox gl js/) [Interactions API Guide](https://docs.mapbox.com/mapbox gl js/guides/user interactions/interactions/) [GeoJSON Specification](https://geojson.org/) [Directions API](https://docs.mapbox.com/api/navigation/directions/) [Store Locator Tutorial](https://docs.mapbox.com/help/tutorials/building a store locator/)

mapbox-store-locator-patterns