> ## Documentation Index
> Fetch the complete documentation index at: https://docs.digifist.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Store Locator

> Interactive Google Maps with store locations, search, and detailed store information

## What It Does

The **Store Locator** section displays an interactive Google Maps showing your physical store locations with pins, detailed store information, and search functionality. Customers can view store addresses, hours, contact info, and get directions—perfect for brick-and-mortar retailers with multiple locations.

Each store location is a "Pin" block with customizable details (name, address, image, phone, hours, coordinates). The section offers three layout modes: interactive map with sidebar, static images with sidebar, or map-only display. Search functionality helps customers find nearest locations.

## Getting Started

<Steps>
  <Step title="Get Google Maps API Key">
    Create a free Google Maps API key at [Google Cloud Console](https://console.cloud.google.com/google/maps-apis/). Enable Maps JavaScript API and paste key in section settings.
  </Step>

  <Step title="Add Store Pin Blocks">
    Add a Pin block for each location. Section includes 2 sample pins by default—edit or delete them.
  </Step>

  <Step title="Configure Store Details">
    For each pin, add store name, address, phone, hours, and image. Find latitude/longitude coordinates using Google Maps (right-click location → coordinates).
  </Step>

  <Step title="Choose Layout & Appearance">
    Select layout (map + sidebar, image + sidebar, or map only), section width (fullwidth/page), and height (55-100vh).
  </Step>
</Steps>

## Settings

<Tabs>
  <Tab title="Section Settings">
    <AccordionGroup>
      <Accordion title="Google Maps API Key" icon="key">
        **Type:** Textarea\
        **Required:** Yes (for map display)\
        **Info:** "You should create a Google Maps API key and add it here to display the map. [Learn more](https://developers.google.com/maps/documentation/javascript/get-api-key)"

        API key authenticates your site with Google Maps to display interactive maps.

        ### How to Get API Key

        **Step 1: Google Cloud Console**

        * Go to [Google Cloud Console](https://console.cloud.google.com/)
        * Sign in with Google account (free)
        * Create new project or select existing one

        **Step 2: Enable APIs**

        * Navigate to "APIs & Services" → "Library"
        * Search for "Maps JavaScript API"
        * Click "Enable"

        **Step 3: Create Credentials**

        * Go to "APIs & Services" → "Credentials"
        * Click "Create credentials" → "API key"
        * Copy the generated API key

        **Step 4: Secure Your Key** (Important!)

        * Click "Edit API key"
        * Under "Application restrictions," select "HTTP referrers"
        * Add your store domain: `yourdomain.com/*`
        * Add Shopify CDN: `*.myshopify.com/*`
        * Save restrictions

        **Step 5: Paste in Theme**

        * Paste API key in "Google Maps API Key" field
        * Save section
        * Map should now display

        \###billing & Costs

        **Free tier:**

        * \$200 monthly credit (covers \~28,000 map loads)
        * Most small-medium stores stay within free tier
        * No credit card required initially (but recommended)

        **Pricing past free tier:**

        * Maps JavaScript API: \$7 per 1,000 loads
        * Rarely exceeded unless high traffic

        **Monitor usage:**

        * Check [Google Cloud Console](https://console.cloud.google.com/) → "Billing"
        * Set up budget alerts

        ### Without API Key

        **If left empty:**

        * Map won't display (empty gray box or error message)
        * Store info sidebar still works (addresses, hours, images)
        * Consider using "Image and sidebar" layout if no API key

        ### Troubleshooting

        **Map not showing:**

        * Verify API key copied correctly (no extra spaces)
        * Check Maps JavaScript API is enabled
        * Confirm domain restrictions include your store URL
        * Check browser console for API errors

        **"This page can't load Google Maps correctly" error:**

        * API key restrictions too strict (temporarily remove restrictions to test)
        * Billing not enabled (add credit card to Google Cloud account)
        * Daily quota exceeded (check Google Cloud Console usage)

        **Best practice:** Always restrict API key to your domain(s) to prevent unauthorized use.
      </Accordion>

      <Accordion title="Zoom Level" icon="magnifying-glass-plus">
        **Type:** Range slider\
        **Range:** 0-21 (step: 1)\
        **Default:** 4

        Controls initial map zoom when section loads. Lower numbers show wider geographic area, higher numbers show closer street-level detail.

        ### Zoom Level Guide

        **0-3: World/Continent** (Very zoomed out)

        * 0: Entire world visible
        * 1: Continent-level view
        * 2: Large countries/regions
        * 3: Multiple countries

        **Use when:** International locations across continents

        **4-6: Country/State** ← **Default: 4**

        * 4: Large country (USA, China, Brazil)
        * 5: Multiple states/provinces
        * 6: Single state/large region

        **Use when:** Locations across different states/regions

        **7-9: Region/City Area** (Common for multiple locations)

        * 7: Metropolitan area
        * 8: City + suburbs
        * 9: Single city

        **Use when:** Multiple stores within metro area (most common)

        **10-13: Neighborhood/District**

        * 10: Large neighborhood
        * 11: District
        * 12: Small neighborhood
        * 13: Few blocks

        **Use when:** Stores very close together (downtown locations)

        **14-21: Street Level** (Very zoomed in)

        * 14-15: Street view
        * 16-18: Building level
        * 19-21: Extreme close-up (rarely used)

        **Use when:** Single store location only

        ### Choosing Optimal Zoom

        **Multiple far-apart locations:**

        * Zoom: 4-7 (shows all pins on initial load)
        * Example: Stores across entire country

        **Multiple nearby locations:**

        * Zoom: 8-10 (city/metro area visible)
        * Example: 3 stores in Chicago metro area

        **Single store:**

        * Zoom: 14-16 (street-level detail)
        * Example: Only one flagship location

        **Tip:** After setting zoom, test on live site. Customers can zoom in/out manually, but initial zoom sets first impression.

        **Recommendation:** Use 4-7 for multi-location businesses (default 4 works well), 14+ for single locations.
      </Accordion>

      <Accordion title="Section Width" icon="arrows-left-right">
        **Type:** Select dropdown\
        **Options:** Full width, Page width\
        **Default:** Full width

        Controls maximum width of the store locator section.

        ### Full Width (Default)

        * Section spans entire viewport width (edge to edge with global margins)
        * Map fills maximum space
        * **Best for:** Interactive map layouts (map + sidebar, map only)
        * **Rationale:** Maps benefit from wider space for better browsing

        ### Page Width

        * Constrained to standard page content width (\~1000-1400px depending on theme)
        * Creates more contained, focused appearance
        * **Best for:** Image + sidebar layout, single store
        * **Rationale:** Matches width of other page sections for consistency

        ### Choosing Width

        **Use Full Width when:**

        * Layout is "Map and sidebar" or "Map" only
        * Multiple stores (large area to display)
        * Map is primary feature
        * Want immersive, full-screen map experience

        **Use Page Width when:**

        * Layout is "Image and sidebar"
        * Single store (no need for wide map)
        * Other page sections are page-width (maintains consistency)
        * Prefer more traditional page structure

        **Recommendation:** Stick with Full Width for map-based layouts, use Page Width for image-based or single-location pages.
      </Accordion>

      <Accordion title="Height" icon="arrows-up-down">
        **Type:** Range slider\
        **Range:** 55-100vh (step: 5vh)\
        **Default:** 100vh\
        **Note:** Desktop only

        Controls vertical height of the store locator section using viewport height (vh) units.

        ### Understanding "vh" Units

        **1vh = 1% of viewport (browser window) height**

        * 100vh = Full screen height
        * 50vh = Half screen height
        * 75vh = Three-quarters screen height

        **Dynamic sizing:**

        * Adjusts to user's screen size automatically
        * Tall monitor = taller section
        * Short monitor = shorter section

        ### Height Options

        **100vh (Full screen)** ← **Default**

        * Section fills entire browser window height
        * **Pro:** Immersive, app-like experience
        * **Con:** Hides content below fold
        * **Best for:** Dedicated store locator page, map is primary content

        **80-90vh (Nearly full screen)**

        * Shows top of next section (hints at more content below)
        * **Pro:** Immersive but signals scroll-ability
        * **Best for:** Map is main feature but other content exists below

        **70-75vh (Three-quarters)**

        * Balanced—significant presence without dominating
        * **Pro:** Room for content above/below without scrolling
        * **Best for:** Multi-section pages (hero, store locator, testimonials, footer)

        **60-65vh (Two-thirds)**

        * More compact, leaves substantial space for other sections
        * **Pro:** Integrates well with content-heavy pages
        * **Best for:** Homepage with multiple sections

        **55vh (Minimum)**

        * Smallest allowed, still functional
        * **Pro:** Doesn't dominate page, more like standard section
        * **Best for:** Store locator as supporting feature, not main content

        ### Desktop Only Note

        **Mobile behavior:**

        * Height setting ignored on mobile (under 768px typically)
        * Mobile uses auto height based on content and screen size
        * Map typically \~400-500px on mobile
        * Sidebar scrolls independently

        **Why desktop-only:**

        * Mobile screens vary widely (iPhone SE vs iPad)
        * Fixed vh on mobile creates usability issues (too tall or too short)
        * Auto height ensures optimal mobile experience

        ### Choosing Height

        **Dedicated "Store Locator" page:**

        * Height: 90-100vh (full/nearly full screen)
        * Map is the page (like Google Maps app)

        **Store locator on homepage:**

        * Height: 60-75vh (significant but not dominating)
        * Allows room for hero, products, etc.

        **"Contact Us" or footer area:**

        * Height: 55-65vh (compact integration)
        * Part of larger content mix

        **Recommendation:** Use 100vh for dedicated pages, 70-75vh for multi-section pages, 55-60vh for secondary features.
      </Accordion>

      <Accordion title="Section Layout" icon="table-columns">
        **Type:** Select dropdown\
        **Options:** Map and sidebar, Image and sidebar, Map\
        **Default:** Image and sidebar

        Controls the primary layout configuration of the store locator section.

        ### Image and Sidebar (Default)

        **Desktop layout:**

        ```
        [Store Images Vertical] | [Map]
        ```

        * Left: Scrollable sidebar with store cards (images, addresses, hours)
        * Right: Interactive Google Map with pins

        **Best for:**

        * Showcasing store aesthetics (photos of locations)
        * Visual browsing experience
        * Businesses where store ambiance matters (cafes, boutiques, showrooms)

        **When API key empty:**

        * Sidebar still works (customers can browse store info)
        * Map area empty (graceful degradation)

        ### Map and Sidebar

        **Desktop layout:**

        ```
        [Store List (No Images)] | [Map]
        ```

        * Left: Scrollable list of store information (no large images, more compact)
        * Right: Interactive Google Map with pins

        **Best for:**

        * Functional/utility focus (find nearest store fast)
        * Many locations (list format handles more stores)
        * Faster loading (fewer/smaller images)
        * Professional/corporate aesthetic

        **Difference from "Image and sidebar":**

        * No prominent store images (images smaller or absent)
        * More stores visible in sidebar without scrolling
        * Less visual, more informational

        ### Map (Full width)

        **Desktop layout:**

        ```
        [Full Width Interactive Map]
        ```

        * Map occupies entire section
        * No sidebar visible initially
        * Click pins to see store info in map tooltip/popup

        **Best for:**

        * Many locations (50+)
        * Focus on geographic distribution
        * Clean, uncluttered interface
        * Customers prefer exploring map directly vs scrolling list

        **Store info access:**

        * Click map pins opens info window (name, address, directions link)
        * Hover/click shows tooltip

        ### Mobile Behavior (All Layouts)

        **All layouts on mobile:**

        * Stacked vertically (map above or below store list)
        * Store list becomes swipeable carousel (if 2+ stores)
        * Map height reduced (\~400px)
        * Layout setting has minimal visual effect (mobile optimizes automatically)

        ### Choosing Layout

        **Image and sidebar when:**

        * Store aesthetics are important (design-forward retail, hospitality)
        * Under 10-15 locations (sidebar remains scannable)
        * You have high-quality store photos
        * Visual browsing preferred over map-based searching

        **Map and sidebar when:**

        * You have many locations (15+)
        * Function over form (customers just need address/hours)
        * Limited or no store photos
        * Faster page load priority (fewer images)

        **Map only when:**

        * You have many locations (20+)
        * Customers know what they're looking for (browse map, not list)
        * Clean, minimal interface preferred
        * Geographic distribution is key selling point ("We're everywhere!")

        **Recommendation:** Start with "Image and sidebar" (default) for visual appeal, switch to "Map and sidebar" for many locations, use "Map" for 50+ locations or minimal aesthetic.
      </Accordion>

      <Accordion title="Spacing - Desktop" icon="up-down">
        **Type:** Select dropdown\
        **Options:** Default, Medium, Compact, None\
        **Default:** Default

        Controls vertical spacing (padding) above and below the section on desktop.

        * **None:** No spacing (section touches adjacent sections edge-to-edge)
        * **Compact:** Minimal spacing (\~20-30px)
        * **Default:** Standard spacing (\~40-60px) ← **Recommended**
        * **Medium:** Generous spacing (\~80-100px)

        ### When to Adjust

        **Default (most cases):**

        * Balanced spacing between sections
        * Professional appearance
        * Breathes without feeling disconnected

        **Compact:**

        * When map is part of dense content flow
        * Faster vertical page scanning
        * More content visible without scrolling

        **Medium:**

        * Store locator is featured/hero section
        * Standalone page (only section)
        * Dramatic, separated presentation

        **None:**

        * Edge-to-edge layout (rare)
        * Custom designs where spacing handled elsewhere
        * Map immediately follows hero with no gap

        **Recommendation:** Keep Default for standard layouts.
      </Accordion>

      <Accordion title="Spacing - Mobile" icon="mobile">
        **Type:** Select dropdown\
        **Options:** Default, Compact, None\
        **Default:** Compact

        Controls vertical spacing on mobile devices.

        * **None:** No spacing
        * **Compact:** Minimal spacing (\~15-20px) ← **Default**
        * **Default:** Standard spacing (\~30-40px)

        **Mobile default is Compact** to reduce scrolling on smaller screens.

        **When to adjust:**

        * **Default:** More breathing room on mobile (use if section feels cramped)
        * **None:** Edge-to-edge mobile design (rare)

        **Recommendation:** Stick with Compact (default) for mobile.
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Pin Blocks (Stores)">
    <AccordionGroup>
      <Accordion title="Store Pin Block" icon="location-dot">
        **Block Type:** Pin\
        **Limit:** Unlimited\
        **Preset:** 2 sample pins (Paris, Rome coordinates)

        Each Pin block represents one physical store location with all details.

        ### Pin Settings

        **Store Info:**

        **Store Name** (Text, required)

        * Name of this specific location
        * Examples: "Downtown Chicago," "SoHo Flagship," "Portland Store"
        * Appears: Map tooltip, sidebar card title, search results

        **Address** (Textarea)

        * Full mailing address
        * Format: Street, City, State ZIP, Country
        * Example: "123 Main St, Seattle, WA 98101, USA"
        * Appears: Sidebar card, map info window
        * **Best practice:** Use full address with ZIP/postal code for accuracy

        **Phone** (Text)

        * Store contact phone number
        * Format: Include country code for international ("+1 555-123-4567")
        * Appears: Sidebar card, map info window
        * **Clickable:** Automatically becomes "tel:" link on mobile (tap to call)

        **Opening Hours** (Rich text)

        * Store hours of operation
        * Supports formatting (bold days, line breaks)
        * Example:

        ```
        Mon-Fri: 10am-8pm
        Saturday: 10am-6pm
        Sunday: Closed
        ```

        * Appears: Sidebar card (below address)
        * **Tip:** Use line breaks (`<br/>`) for multi-line hours

        **Store Image** (Image picker)

        * Photo of storefront, interior, or location landmark
        * **Recommended size:** 800x600px to 1200x900px
        * **Aspect ratio:** 4:3 or 16:9 works well
        * **File size:** Under 300KB (compress before upload)
        * Appears: Sidebar card (large image in "Image and sidebar" layout)
        * **Optional:** Leave blank for "Map and sidebar" or "Map" layouts

        **Store Location (Coordinates):**

        **Latitude** (Text, required for map pin)

        * North/South coordinate
        * Format: Decimal degrees (e.g., "48.85850418716008")
        * **How to find:** Right-click location in Google Maps → Copy coordinates (first number)
        * [Learn more](https://support.google.com/maps/answer/18539)

        **Longitude** (Text, required for map pin)

        * East/West coordinate
        * Format: Decimal degrees (e.g., "2.294803163425021")
        * **How to find:** Right-click location in Google Maps → Copy coordinates (second number)
        * [Learn more](https://support.google.com/maps/answer/18539)

        **Custom Tooltip Text** (Textarea, optional)

        * Text shown when hovering over map pin
        * **Default:** Uses "Store Name" if empty
        * **Use when:** You want different text on hover vs sidebar (e.g., "Click for directions" vs store name)
        * **Most cases:** Leave empty (store name is sufficient)

        **Actions:**

        **Directions Button Name** (Text)

        * Label for "Get Directions" button
        * Default: "Directions"
        * Alternatives: "Get Directions," "Navigate," "View on Map"
        * Appears: Sidebar card as button

        **Custom Directions Link** (URL, optional)

        * Override automatic Google Maps directions link
        * **Default behavior (empty):** Generates Google Maps directions URL automatically based on coordinates
        * **Use custom link when:**
          * You prefer Apple Maps, Waze, or other nav app
          * You have specific directions page
          * Building entrance is tricky (link to detailed instructions)
        * Example: `https://waze.com/ul?ll=48.8585,2.2948&navigate=yes`
        * **Most cases:** Leave empty (auto-generated link works best)

        ### Finding Coordinates (Step-by-Step)

        1. Go to [Google Maps](https://www.google.com/maps/)
        2. Search for your store address
        3. Right-click on the exact location (red pin)
        4. Click "Copy" on the coordinates that appear
        5. Paste into Notepad—format is: `latitude, longitude`
        6. **First number = Latitude** (paste in Latitude field)
        7. **Second number = Longitude** (paste in Longitude field)

        **Example:** `48.85850418716008, 2.294803163425021`

        * Latitude: 48.85850418716008
        * Longitude: 2.294803163425021

        ### Preset Sample Data

        **Pin 1 (Paris):**

        * Store Name: "Your store name"
        * Address: "Your store address"
        * Hours: "Mon-Sat: 10am-8pm, Sunday"
        * Phone: "+01 234 567 8900"
        * Latitude: 48.85850418716008 (Eiffel Tower area)
        * Longitude: 2.294803163425021

        **Pin 2 (Rome):**

        * Same sample data, different coordinates
        * Latitude: 41.902331905731444 (Colosseum area)
        * Longitude: 12.45445667605574

        **Action:** Replace sample data with your actual store information.
      </Accordion>
    </AccordionGroup>
  </Tab>
</Tabs>

## Best practices

<CardGroup cols={2}>
  <Card title="Secure Your API Key" icon="lock">
    Always restrict API key to your domain(s) in Google Cloud Console. Unrestricted keys can be stolen and used, incurring charges to your account.
  </Card>

  <Card title="Accurate Coordinates" icon="crosshairs">
    Use exact latitude/longitude from Google Maps (right-click location). Approximate coordinates place pin in wrong spot, confusing customers.
  </Card>

  <Card title="Complete Store Info" icon="circle-info">
    Fill all fields (name, address, phone, hours, image). Incomplete info frustrates customers trying to visit. Hours and phone are especially critical.
  </Card>

  <Card title="High-Quality Store Photos" icon="camera">
    Use clear, well-lit photos of storefront or interior (under 300KB). Helps customers recognize location and builds trust in brick-and-mortar presence.
  </Card>

  <Card title="Test Directions Links" icon="route">
    Click "Directions" button for each store to verify link works. Auto-generated links usually work, but test custom links thoroughly.
  </Card>

  <Card title="Optimize Zoom Level" icon="magnifying-glass">
    Set zoom to show all pins on initial load (4-7 for multi-location, 14+ for single store). Customers shouldn't have to zoom out to find locations.
  </Card>

  <Card title="Mobile-Friendly Hours" icon="clock">
    Use simple, readable hour formats. "Mon-Fri: 10am-8pm" better than "Monday through Friday: 10:00 AM - 8:00 PM" (takes less space on mobile).
  </Card>

  <Card title="Monitor API Usage" icon="chart-line">
    Check Google Cloud Console monthly for map load count. Set budget alerts at \$50 to catch unexpected usage before bills accumulate.
  </Card>
</CardGroup>

## Common Use Cases

### Multi-Location Retail Chain

**Stores:** 5-20 locations across state or region

**Setup:**

* Layout: "Map and sidebar" (efficient list + map)
* Zoom: 7-9 (shows city/metro area)
* Height: 75vh (significant presence on "Locations" page)
* Each pin: Store name, full address, phone, hours (M-Sat 10-8, Sun 12-6), storefront photo

**Best for:** Apparel, home goods, bookstores, sporting goods

### Franchise/Quick-Service Restaurant

**Stores:** 10-50+ locations

**Setup:**

* Layout: "Map" only (many locations, list would be long)
* Zoom: 6-8 (regional view)
* Height: 100vh (full-screen map experience)
* Each pin: Restaurant name, address, phone, hours (daily 11am-10pm), no images (speeds up loading)

**Best for:** Fast food, coffee shops, car washes, gyms

### Single Flagship Store

**Stores:** 1 location

**Setup:**

* Layout: "Image and sidebar" (showcase beautiful storefront)
* Zoom: 15-16 (street-level detail, exact building visible)
* Height: 70vh (integrated on "Contact" or "Visit Us" page)
* Single pin: Store name, address, phone, detailed hours, high-quality store photo

**Best for:** Boutiques, flagship stores, galleries, brand showrooms

### Regional Business (Showrooms/Offices)

**Stores:** 3-8 locations across multiple cities

**Setup:**

* Layout: "Image and sidebar"
* Zoom: 5-7 (state/region level)
* Height: 80vh (prominent on "Locations" page)
* Each pin: Office name (e.g., "Seattle Showroom"), address, phone, hours (appointment-based: "By appointment: Call to schedule"), professional office photo

**Best for:** Furniture showrooms, B2B offices, design studios, real estate agencies

### Hospitality/Multiple Properties

**Stores:** 2-10 properties (hotels, vacation rentals, venues)

**Setup:**

* Layout: "Image and sidebar" (showcase each property visually)
* Zoom: 8-10 (metro area if nearby, 5-7 if spread out)
* Height: 85vh (major page feature)
* Each pin: Property name, address, phone, check-in hours, hero photo of property

**Best for:** Hotels, Airbnb hosts with multiple properties, event venues, resorts

### Pop-Up/Temporary Locations

**Stores:** 1-3 current pop-ups

**Setup:**

* Layout: "Map and sidebar" (simple, quick updates)
* Zoom: 9-11 (neighborhood level)
* Height: 70vh
* Each pin: "Pop-up: \[City Name]", address, hours (include dates: "Open Nov 1-30, Daily 10am-6pm"), phone, event photo

**Best for:** Seasonal shops, market vendors, temporary installations, trade show locations

## Layout Behavior

### Desktop Layout by Mode

**Image and Sidebar:**

```
Desktop:
[Sidebar - Scrollable]    [Map - Interactive]
[Store 1 Card - Large]    [Pin 1]
[Store 2 Card - Large]    [Pin 2]
[Store 3 Card - Large]    [Pin 3]
[Search Bar - Top]        [Zoom Controls]
```

* Sidebar: \~30-40% width, scrollable, prominent images
* Map: \~60-70% width, full height
* Click pin: Map pans to location, sidebar scrolls to matching card

**Map and Sidebar:**

```
Desktop:
[Sidebar - Compact List]  [Map - Interactive]
[Store 1 - Text]          [Pin 1]
[Store 2 - Text]          [Pin 2]
[Store 3 - Text]          [Pin 3]
[Search Bar - Top]        [Zoom Controls]
```

* Sidebar: \~30-40% width, more stores visible (compact cards, smaller/no images)
* Map: \~60-70% width, full height

**Map Only:**

```
Desktop:
[Full Width Map]
[Pin 1] [Pin 2] [Pin 3]
[Zoom Controls, Search]
```

* Map: 100% width, full height
* No sidebar visible
* Click pin: Info window/tooltip shows store details

### Mobile Layout (All Modes)

```
Mobile (Stacked):
[Map - 400-500px height]
[Pin 1] [Pin 2] [Pin 3]

[Store Cards - Swipeable Carousel]
[← Store 1 →] (Swipe left/right)
[Store 2]     (Hidden until swiped)
[Store 3]     (Hidden until swiped)
```

* Map: Full width, \~40-50vh height
* Store carousel: Full width, swipe to browse (if 2+ stores)
* Search: Above map or in collapsed dropdown
* All layout modes look similar on mobile (stack pattern)

### Search Functionality

**Search bar** (appears when 2+ pins):

* Desktop: Top of sidebar
* Mobile: Above map or in dropdown
* **Function:** Filters visible pins by location name/address
* **Example:** Type "Seattle" → only Seattle stores visible, map pans to Seattle area
* **Autocomplete:** May suggest store names as you type (theme-dependent)

### Pin Interaction

**Click pin behavior:**

1. Map centers on clicked pin
2. Sidebar scrolls to matching store card (highlights it)
3. Info window/tooltip opens on map with store name + address
4. "Directions" link in info window (opens Google Maps directions)

**Click store card in sidebar:**

1. Map pans to that store's pin
2. Pin bounces/highlights briefly
3. Info window opens on pin

## Related Sections

* **[Contact Form](/themes/mojave/contact-form)** - Often paired with store locator on Contact page
* **[Footer](/themes/mojave/footer/footer)** - May include condensed store info or "Find a Store" link
* **[Rich Text](/themes/mojave/richtext)** - Use for additional location details or instructions above/below map

## Technical Notes

### Google Maps API

**API used:** Maps JavaScript API

**Required features:**

* Map rendering (basic map display)
* Markers (store location pins)
* Info windows (store details on pin click)
* Geocoding (address → coordinates, used for search)

**Optional enhancements (requires additional APIs):**

* Directions API (custom routing)
* Places API (nearby POI, autocomplete)

### Coordinate Precision

**Decimal places significance:**

* **4 decimals** (48.8585): \~11 meters accuracy (city block level)
* **6 decimals** (48.858504): \~0.1 meters (building entrance exact)
* **8+ decimals**: \~1mm (unnecessarily precise)

**Recommendation:** Use 6-8 decimals from Google Maps (sufficient for storefront accuracy).

### Performance Optimization

**Image loading:**

* Store images lazy load (only visible sidebar cards)
* Compress images to under 300KB each
* Use WebP format if theme supports (smaller file size, faster)

**Map loading:**

* Map renders after page load (non-blocking)
* API script loads asynchronously
* Total section load: 500ms-2s depending on image count

**Search performance:**

* Client-side filtering (no server requests)
* Instant results as you type
* Scales to 50+ stores without performance issues

### Browser Compatibility

**Supported browsers:**

* Chrome, Firefox, Safari, Edge (latest 2 versions)
* Mobile Safari (iOS 12+)
* Chrome Mobile (Android 5+)

**Graceful degradation:**

* No API key: Sidebar still works, map empty
* JavaScript disabled: Static list of stores (no map interaction)
* Old browsers: Fallback to basic map (no advanced features)

### Accessibility

**Keyboard navigation:**

* Tab through store cards in sidebar
* Enter to select store (pans map to pin)
* Arrow keys to pan map
* +/- keys to zoom

**Screen reader support:**

* Store cards have semantic HTML (`<address>`, `<time>`, etc.)
* Map pins have ARIA labels with store names
* "Get Directions" links clearly labeled

**Focus management:**

* Clicking pin brings focus to info window
* Clicking sidebar card brings focus to map pin
* Focus visible (outline on interactive elements)

## Troubleshooting

**Map not displaying (empty gray box):**

* Verify Google Maps API key is correct (copy/paste carefully)
* Check Maps JavaScript API is enabled in Google Cloud Console
* Confirm API key restrictions allow your domain
* Check browser console for API error messages (F12 → Console tab)
* Verify billing is enabled on Google Cloud account (even with free tier, card required after initial setup)

**Pins in wrong location:**

* Verify latitude/longitude coordinates are correct (swap lat/long by mistake?)
* Re-copy coordinates from Google Maps (right-click exact location)
* Check for typos in coordinates
* Use 6-8 decimal places (4 or fewer = imprecise)

**Search not working:**

* Search requires 2+ store pins (hidden with only 1 store)
* Clear browser cache and reload
* Check if store names/addresses contain searchable text
* Verify JavaScript isn't blocked (some ad blockers affect search)

**Directions link broken:**

* If using "Custom Directions Link," verify URL is valid (test in browser directly)
* If using auto-generated (field empty), verify coordinates are correct
* Check for special characters in address breaking URL encoding
* Test link by clicking "Directions" button in live preview

**Images not loading in sidebar:**

* Check image file sizes (keep under 500KB, ideally under 300KB)
* Try different image format (JPG vs PNG)
* Verify images uploaded successfully (re-upload if needed)
* Check if images are too large (browser may timeout loading)

**Zoom level not saving:**

* Verify you're editing correct section (multiple store locator sections if on different pages?)
* Hard refresh browser after saving (Cmd/Ctrl + Shift + R)
* Clear theme cache if available in theme settings
* Test on live site (Theme Customizer may cache differently)

**Section too short/tall on desktop:**

* Adjust "Height" setting (55-100vh range)
* Remember setting is desktop-only (mobile uses auto height)
* Preview on live site (editor may render differently)
* Check other CSS isn't conflicting (contact theme support if section height locked)

**Mobile layout broken:**

* Test on actual device (not just browser resize)
* Clear mobile browser cache
* Check image sizes (very large images may cause layout issues on mobile)
* Verify theme JavaScript isn't conflicting (disable other sections temporarily to isolate issue)

**API usage/billing concerns:**

* Monitor usage in Google Cloud Console → "APIs & Services" → "Dashboard"
* Set budget alerts at $50, $100 thresholds
* Most stores stay within \$200/month free tier (\~28,000 map loads)
* High usage? Consider caching strategies or alternative map providers (Mapbox, OpenStreetMap)

**Store hours not displaying:**

* Verify "Opening Hours" field has content
* Use rich text formatting (`<p>Mon-Fri: 10-8</p>`)
* Check for HTML errors (unclosed tags)
* Preview on live site (Theme Customizer may not render rich text fully)

**Too many stores (performance issues):**

* Consider "Map only" layout (no image loading in sidebar)
* Compress store images aggressively (under 100KB each)
* Reduce number of visible stores (group by region, use multiple pages)
* Consider alternative: external store locator service (Storemapper, etc.)