# Show your stores on your online store

The app adds three blocks to your theme. You place them in the theme editor, like any section, and they take your theme's fonts and colors.

| Block | What it shows | Where to add it |
| --- | --- | --- |
| **Store locator** | A map and the list of your stores, with a search. | On a page, for example "Our stores". |
| **Store page** | The page of one store: photos, hours, services, directions. | On the **Store page** template, once for all your stores. |
| **Store list** | Your stores as a grid of cards, grouped by country, without a map. | On a page, instead of or alongside the store locator. |

Only active stores show, and each one on the channels ticked on its page in the app: the store locator, its page, or both.

## Add a block

1. In Shopify, open **Online Store > Themes**, then click **Customize**.
2. Open the page or template where the block goes.
3. Click **Add section**, then open the **Apps** tab.
4. Choose the block, then click **Save**.

The app's setup guide walks you through the store locator and the store pages. See [Set up the app](/docs/getting-started/set-up/).

## The store locator

### What your visitors see

- **The map and the list**: the list holds the stores of the area the store locator framed, on arrival, after a search, a filter or **Near me**. Your types come first, in the order of the [Settings](/docs/merchants/settings/), then the cities in alphabetical order, a city with several stores under a heading; or by distance when the visitor shared their location. Moving or zooming the map leaves the list as it is: when the map shows stores the list doesn't have, a **Search this area** button appears on the map, then **Back to …** brings back the list before. The list writes its stores as the visitor scrolls: even with thousands of stores, the page stays smooth. Each store has its type's marker, set in the [Settings](/docs/merchants/settings/#a-types-marker), with a legend at the bottom of the map on a computer.
- **Groups of stores**: when the view holds more than 50 stores, the stores too close to tell apart become one circle with their number; tapping it zooms in. At a city's scale, every store has its own marker.
- **A link under the list brings back the arrival's view** once the list left it (after a search, say): "Show all stores in “France”", or "Show the stores near you".
- **With distances**, each is on the right of the name, and the first store is marked "Nearest".
- **For each store**: its name, its type, its address, its phone, and **Store page →** if it has a page; the arrow says the visitor leaves the store locator.
- **Tapping a card** centers the map on the store and marks the card; the list keeps its stores. Tapping a marker marks its card too. The popup on the map adds the address, whether it is open now, the phone, **Directions** and **Store page →**.
- **On a phone**, the search, **Near me** and the filters share one line above a shorter map, and the list scrolls in its own box below it. The cards have **Directions** (on a computer it is in the popup; whether the store is open is on the card everywhere); the popup only keeps the name, whether it is open now, the phone and **Store page →**. No legend on a phone: the type is written on each card.
- **The search**, by city, postal code or store name. Suggestions appear while typing: the cities with their number of stores, then the stores. When no city of yours matches, places appear under the suggestions (cities, postal codes): choosing one shows its nearest stores, with their distance, and says so when even the nearest is far. Until the visitor searches or shares their location, a sentence under the search invites them to.
- **Near me**: the visitor shares their location, and the map shows their 3 nearest stores, with their distance.
- **The filters** by type and by service, under the search.

The store locator keeps the search, the filters and the map's position in the page's address: a visitor coming back from a store page finds the map as they left it.

### Its main settings

| Setting | What it does |
| --- | --- |
| **Title** | The page's title, above the map ("Find a store" when you add the block). Empty it if your page template already shows the page's title, so there is a single title. |
| **Map view on arrival** | What the map shows when the visitor arrives: the **Market of the online store** (the country chosen in the theme's country selector, the default), the **Visitor's position**, a **Fixed country**, or **All stores**. |
| **If no store in that area** | What the map shows when the country has no store: the **Nearest country with stores**, the **Country with the most stores**, or **All stores**. A sentence tells the visitor. |
| **Search**, **Type filter**, **Services filter** | Show or hide the search and each filter. |
| **City shortcuts** | Under the search, the cities with the most stores, one tap away. |
| **Map on demand on a phone** | On a phone, no map on arrival: a **Show on map** button opens it. The visitor starts with their city or their location. |
| **Fill the window height**, **Map height** | The map's size. |

Each setting in detail is in [Theme blocks](/docs/developers/theme-blocks/).

:::note[Good to know]
- Every type is checked when the visitor arrives. Stores without a type are never hidden by the filter.
- When the visitor checks several services, only the stores offering all of them stay.
- The search finds your stores by their name, address, city or postal code; a city where you have no store is looked up with the map's provider (Mapbox, or Google with the Geocoding API on your key), never a street address.
:::

## The store pages

Each active store published as a page has its own address, for example `your-store.com/pages/stores/paris-le-marais`. All these pages share a single template in your theme, **Store page**: you add the **Store page** block to it once.

### What your visitors see

- The store's name, its main photo as a banner, and its type.
- **About the store**: its description.
- **Address**, with **Get directions**, and its **Services**.
- **Contact**: phone and email.
- **Opening hours**, with an **Open now** or **Closed** badge, at the store's local time, and its next **Exceptional hours**.
- A map: clicking it opens the directions in Google Maps.
- Its other photos.
- **Nearby stores**: the 3 nearest stores that have a page.

### Its settings

| Setting | What it does |
| --- | --- |
| **Title** | `[name]` stands for the store's name. Empty it when you add your theme's heading block above, connected to the store's name. See [Set up the app](/docs/getting-started/set-up/#4-create-the-template-for-the-individual-pages). |
| **Show photos**, **Show map**, **Show nearby stores** | Each part of the page. |
| **Link to all stores** | A link to your store locator page, next to the title. Empty, no link. |

:::note[Good to know]
- The pages are served by Shopify, like your other pages: they stay online even if the app is unavailable, and they are in your store's sitemap.
- A draft store, or one without its page ticked, has no page: its address returns an error.
- To change the middle word of the address ("stores"), see [Settings](/docs/merchants/settings/#store-pages).
:::

## The store list

Another way to show your stores, without a map: handy for a brand in a few countries, or for an "Our stores in France" or "Our stockists" page.

### What your visitors see

- The block's title ("Our stores" by default; empty, no title).
- A heading per country, then the grid of its stores (or a heading per type, or a single grid: see **Group by**), in alphabetical order (or by city, or by type: see **Sort by**).
- A **Filters** button at the top left, with the number of stores on the right: the countries, types and services to show. It turns darker, with the number of filters in use ("Filters (2)"), once a filter narrows the list.
- For each store, a card: main photo, name, type, address, open now, phone and a **Directions** link to Google Maps. The whole card leads to its page, if it has one.

### Its settings

| Setting | What it does |
| --- | --- |
| **Title** | The title above the list. Empty: no title. |
| **Country filter**, **Type filter**, **Services filter** | Show or hide each filter. Without any filter, neither the button nor the number of stores show. |
| **Group by** | **Country** (default), **Type** (your types in the order of the Settings) or **Nothing**. |
| **Sort by** | **Name**, **City, then name**, or **Type, then city**: your types in the order of the Settings, for example your own stores before your stockists. |
| **Only show these countries** | The codes of the countries to show, separated by commas (FR, BE, CH). Empty: every country. |
| **Only show these store types** | The names of the store types to show, as in the app's Settings, separated by commas (Flagship, Stockist). Stores without a type are left out. Empty: every type. |
| **Card size** | Small, medium or large. The list shows as many cards per row as fit in the section's width: one on a phone. |
| **Show store type**, **Show photos**, **Show address**, **Show opening status**, **Show phone link**, **Show directions link** | Each part of the cards, under **Cards content**. |
| **Space above**, **Side margin** | Under **Spacing**: see below. |

:::note[Good to know]
- Beyond 100 stores, a message in the theme editor (only you see it) suggests narrowing the list: for your whole network, the store locator and the country pages are easier to browse. The editor's preview then shows only the first 100 cards; your online store shows them all.
- A mistyped code in **Only show these countries**, or a mistyped type in **Only show these store types**, shows no store, without an error message.
:::

## Country and city pages

A page per country, and if you want a page per city, listing all their stores on the store locator: "Where to buy in Belgium", "Our stores in Lyon". Search engines index them, and find there the way to your store pages. Turn them on in **Settings > Online store pages**, then create their templates in the theme editor ("Country page", "City page") and add the **Country or city page** block to each. The setup guide takes you there.

### What your visitors see

- The breadcrumb (Home / France / Lyon), if you turned it on in the Settings.
- The country's or city's name, and your introduction text, if you wrote one.
- The grid of its stores, with the store list's cards and filters. A store with a page links to it.
- Under the stores: on a country page, links to its city pages; on a city page, a link to its country and to the country's other cities.

The **Store directory** block ("Our stores by country") lists the links to your country pages, and with **Show the cities** their city pages: place it under the store locator, or at the bottom of the country and city pages' templates.

### Its settings

| Setting | What it does |
| --- | --- |
| **Title** | The page's title; `[name]` stands for the country's or city's name. Empty: no title, if your theme's own Heading block is above. |
| **Type filter**, **Services filter** | Show or hide each filter. |
| **Group by** | **Type**: a heading per type, in the order of the Settings. |
| **Title of the cities**, **Link to the country** | The texts of the links under the stores; `[country]` stands for the country's name. |

The cards and spacing settings are the store list's. The prefilled titles are written in your theme editor's language when you add the block.

## Your theme has a fixed header or sections without margins

Two settings, shared by the three blocks, fix the display on some themes:

- **Space above**: if your theme's header stays at the top of the screen and hides the top of the block, set the space to leave above it.
- **Side margin**: if the block goes to the edges of the screen, set the space to leave on each side.

The theme editor's preview shows the result live.