Widget settings reference

Ask the browser for the visitor's location as soon as the widget loads, so they see nearby results without typing.

This automatic prompt is optional. Search near a place always includes a visitor-initiated Use my location action and keeps manual place search available after denial or failure.

Default

Off

Appears when

Automatic location is used to create the search point for "Search near a place".

Lets visitors use browser location without receiving a permission prompt on page load.

Choose a labelled button, a compact icon-only action, or hide it. The wording is editable under Language and the button follows your locator's colors, corners, borders and typography.

Default

Icon and text

Choices

Icon and text, Icon only, Hidden

Appears when

The action creates the search point used by Search near a place.

Lets a visitor bookmark or share a filtered view, and lets you link straight to one from an ad or email.

It updates the address bar of the page the widget sits on, using loc_q and loc_tags so it cannot clash with your own page's parameters.

Default

On

Decides whether typing filters your existing list, or moves the map to a place the visitor names.

Search near a place is the box a customer expects when your locations are spread across a region rather than one town.

Default

Filter by text

Choices

Filter by text, Search near a place

Puts a magnifying glass inside the search box.

A bare bordered box is not obviously a search field until you read its placeholder, and the placeholder is the first thing to go when the box is narrow. The icon survives that.

Default

No icon

Choices

No icon, Magnifying glass

Choose where visitors see the main search field in the locator.

Top row works best for map-first layouts. Above results keeps search next to the list, and Hidden is useful when your page provides its own search.

Default

Top row

Choices

Top row, Above results, Hidden

Address-only is the familiar store-locator behaviour.

Including location details also matches a location's name, description, and custom fields.

Default

Address plus location details

Choices

Address only, Address plus location details

Appears when

"Search near a place" replaces text search with a location lookup.

Choose where visitors see category and open-now filters.

Top row keeps controls visible. Above results keeps them with the list, and Hidden is useful when your page supplies its own filtering controls.

Default

Top row

Choices

Top row, Above results, Hidden

Suggests real addresses as the visitor types. Requires a geocoding provider to be connected first.

Default

Off

Choices

Off, Full address autocomplete, City and region only

Appears when

Autocomplete is used by the near-a-place search box.

Restricts place and address searches to selected countries, using ISO codes such as US, CA, or GB.

Leave blank for worldwide results. Separate multiple countries with commas.

Default

Not set

Appears when

Country filtering only applies to the near-a-place search box.

Adds a distance dropdown next to the search box.

Leave off if your locations are spread far apart, where a radius mostly produces empty results.

Default

Off

Appears when

A radius needs a point to measure from, which needs "Search near a place" turned on.

The distance searched when a visitor has not picked one.

Default

Any distance

Choices

Any distance, 10, 25, 50, 100

Appears when

Only applies once visitors can choose a search radius.

Autodetect uses miles for visitors in the US, UK, and a few others, and kilometres everywhere else.

Default

Autodetect from visitor

Choices

Autodetect from visitor, Miles, Kilometres

Choose how many decimal places appear beside locations.

Default

Smart rounding

Choices

Smart rounding, Whole numbers, One decimal

The distances a visitor can choose from, comma separated, in the units they see. Leave empty for the built-in list.

A city restaurant cares about 1 and 3 miles; a rural distributor cares about 100 and 250. Offering both to either is noise. Any distance is always added at the end so a visitor can widen back out.

Default

Not set

Appears when

Only used when visitors can choose a radius.

What happens to the closest result once a visitor has searched.

A visitor looking at an already-open result is one tap from directions or a call. A visitor looking at ten closed cards has to choose first. This never fires on page load, only after a search or filter.

Default

Leave everything unselected

Choices

Leave everything unselected, Highlight the first result, Open the first result's details, Open its map popup

Show a compact summary of the nearest matching location after a visitor searches near a place.

The summary includes the location name, distance, current opening status, address, phone and Directions. It appears after a place search or visitor-location action, stays hidden on the initial load, and does not appear when a search falls back to the full network.

Default

Hidden

Choices

Hidden, Show after search

Choose what visitors see before they search.

Show the whole network, open near the visitor without a permission prompt, choose a fixed region, or wait for a search. An explicit search or approved browser location always replaces this starting point.

Default

Show all locations

Choices

Show all locations, Start approximately near the visitor, Start at a place I choose, Wait until the visitor searches

Search for the town or region where the locator should open.

Handled looks the place up once and saves its coordinates. Visitor page loads do not repeat the lookup or spend map-provider quota.

Default

Not set

Appears when

Only used when the opening view is a fixed place.

How close the map starts when it opens on a fixed place.

Default

City

Choices

Country, Region, State, City, District, Neighbourhood

Appears when

Only used when the opening view is a fixed place.

Hide the map and results until a visitor searches.

Useful for large location networks where showing every location on first load adds noise.

Default

Off

Re-sorts the list to match wherever the visitor has panned the map.

Feels responsive on desktop, can feel jumpy on touch screens.

Default

Off

Appears when

The layout has no map, so there is nothing to configure here.

Tells the visitor when an automatic browser location request was refused or failed.

A failed Use my location action is always explained because the visitor explicitly requested it. This setting controls only the optional automatic request.

Default

Off

Appears when

There is no automatic location request to report until Visitor location is turned on.

Distance needs a search or a visitor location to mean anything.

Priority uses the featured ranking you set on each location instead.

Default

Priority, then name

Choices

Distance, Name, Priority, then name

Ascending puts the nearest, or the earliest alphabetically, first.

Default

Ascending

Choices

Ascending, Descending

Caps how many locations appear in the list at once. Lower numbers keep long lists manageable on mobile.

Default

30 locations

Showing everything avoids a dead end for the visitor.

A plain empty state is more honest when your locations are genuinely far away.

Default

Show all locations with a note

Choices

Show all locations with a note, Show an empty state

Stops a featured location from being pinned to the top when it is unhelpfully far from the visitor.

Empty means priority always wins, regardless of distance.

Default

No limit

Choices

No limit, Within 25, Within 50, Within 100

Highlight keeps the list in place and moves the map.

Open full details replaces the list with one location's full record and a Back link. Worth it when each location has a lot to say — a photo, a long description, several links — that would make the list unscannable if every card showed it. What the detail pane shows is configured separately, below.

Default

Highlight it on the map

Choices

Highlight it on the map, Open full details

Puts each tag group's name above its own row of chips.

Off shows every tag in one row. Turn this on when a location carries tags from different groups and a bare chip is ambiguous — "Retail" reads very differently under "Location type" than under "Product". Tags with no group keep the plain row.

Default

Off

Immediate renders everything at once.

Paged loads more as the visitor scrolls, which is faster for very large location sets.

Default

Immediate

Choices

Immediate, Load more on scroll

Dropdowns keep the toolbar compact when you have many filters.

Inline checkboxes show every option at once, which suits three or four filters.

Default

Dropdown per group

Choices

Dropdown per group, Inline checkboxes

Match any is the forgiving default and rarely returns nothing.

Match all narrows hard and suits precise catalogues like product stockists.

Default

Match any selected filter

Choices

Match any selected filter, Match all selected filters

Puts the number of matching locations next to each filter.

Lets a visitor see which options are worth picking before they click.

Default

On

Labels each filter group by name. Turn off when you only have one group and the heading is redundant.

Default

On

Zooms the map to the remaining results after a filter is applied, instead of leaving the visitor looking at empty space.

Default

On

Appears when

The layout has no map, so there is nothing to configure here.

Filters you have not put in a group still appear, under a general heading.

Off hides them from visitors without deleting them.

Default

On

Adds an Open now toggle to the toolbar.

Only worth turning on once most of your locations actually have hours filled in.

Default

Off

What the Open now toggle is set to when the widget first loads.

Default

Show all locations

Choices

Show all locations, Show open locations only

Appears when

Only applies when the open-now filter is shown.

Affects the order days are listed in the hours editor and in the widget's opening-hours table. Display only — hours stay stored the same way, so switching it never changes a location.

Default

Monday

Choices

Monday, Sunday

Off starts with just the list and a Show map button, which loads faster and suits pages where the list matters more.

Default

Off

Appears when

The layout has no map, so there is nothing to configure here.

Streets is the standard road map; Light, Dark, and Satellite are the alternate tile styles.

Light is muted so your markers carry the colour, Dark suits dark pages, and Satellite shows aerial imagery with road labels.

Default

Streets

Choices

Streets, Light, Dark, Satellite

Appears when

The layout has no map, so there is nothing to configure here.

Which map renders your locator. Both render on your own account, so you add a key and the map loads bill to you.

You can pick either provider here and preview it straight away — we render the preview on our own key so you can compare before committing. Your own key is needed only when the locator goes live on your site; until you add one, your live locator shows the results list and a note in place of the map. Switching providers changes only how the map looks and renders; visitor search, autocomplete and geocoding are unaffected either way.

Default

Mapbox (your key)

Choices

Mapbox (your key), Google Maps (your key)

Appears when

The layout has no map, so there is nothing to configure here.

Fitting all results keeps every match on screen.

A fixed zoom is more predictable when results are usually in one town.

Default

Fit all results on screen

Choices

Fit all results on screen, Use a fixed zoom level

Appears when

The layout has no map, so there is nothing to configure here.

How far in the map goes when a visitor clicks a single location. Higher is closer. 17 is roughly street level.

Default

17

Appears when

The layout has no map, so there is nothing to configure here.

How far out a visitor can zoom. 0 is the whole world.

Default

0

Appears when

The layout has no map, so there is nothing to configure here.

How far in a visitor can zoom. 22 is fully zoomed in.

Default

22

Appears when

The layout has no map, so there is nothing to configure here.

Off stops the map from swallowing the page scroll when a visitor scrolls past the widget.

That's a common complaint on long pages with an embedded map.

Default

Off

Appears when

The layout has no map, so there is nothing to configure here.

Two fingers lets a visitor scroll the page past the map with one finger.

One finger makes the map easier to move but harder to scroll past.

Default

Two fingers

Choices

Two fingers, One finger

Appears when

The layout has no map, so there is nothing to configure here.

Adds a control that expands the map to fill the browser window.

Default

Off

Appears when

The layout has no map, so there is nothing to configure here.

How tall the map area is on wider screens, in pixels. Narrow screens cap it at half the screen height so the results stay reachable.

Default

260 px

Appears when

The layout has no map, so there is nothing to configure here.

Choose a classic pin, a compact dot or an uploaded custom marker image.

Custom image replaces the pin shape entirely and is not tinted, so the file keeps its own colours. Uploading a custom marker activates it immediately. Existing locators configured to place the account logo inside a pin continue to work, but new marker choices use the clearer Custom image path.

Default

Classic pin

Choices

Classic pin, Dot, Logo inside a pin, Custom image

Appears when

The layout has no map, so there is nothing to configure here.

Tag colour keeps the meaning your tags carry; Brand accent makes the pins match the rest of your locator.

A colour set on an individual location always wins over both. Applying a starter example switches this to Brand accent, because otherwise the pins — the most visible thing on a map — would keep their old colours and the new design would look like it had not applied.

Default

Tag colour

Choices

Tag colour, Brand accent

Appears when

The layout has no map, so there is nothing to configure here.

Replaces overlapping pins with a single numbered cluster that splits apart as the visitor zooms in.

Strongly recommended above about fifty locations.

Default

Off

Appears when

The layout has no map, so there is nothing to configure here.

The shape of the numbered bubble that stands in for overlapping pins.

A circle suits most brands. Rounded and square follow a design that squares off its buttons and cards, where a circular cluster is the one round thing left on the page.

Default

Circle

Choices

Circle, Rounded square, Square

Appears when

Clusters are switched off, so there is no bubble to shape.

A style of your own from Mapbox Studio, used instead of the four built-in themes.

Paste the Style URL from Mapbox Studio (Share -> Style URL), which looks like mapbox://styles/yourname/abc123. The style has to be published and readable by the same token this account uses. Leave blank to keep the built-in theme. This is the setting that lets a locator match a brand whose map is part of its identity, rather than sitting a branded locator next to a stock grey map. It must be a CLASSIC style: the locator draws raster tiles, and Mapbox cannot rasterise its newer Standard style or anything built on top of one, so a Standard-based style renders an empty map. In Studio, a classic style shows "No imports found" in the Imports panel.

Default

Not set

Appears when

Mapbox styles only apply when the map is drawn by Mapbox.

A cloud-styled map ID from the Google Cloud console, used instead of the built-in themes.

Google holds the styling against a Map ID rather than sending it with the request. Set one and Google ignores the built-in theme entirely, including Satellite, because a Map ID carries its own base map. Leave blank to keep the built-in theme.

Default

Not set

Appears when

Map IDs only apply when the map is drawn by Google.

How wide the uploaded marker artwork is drawn, in pixels.

The artwork is fitted inside a square of this size and never stretched, so a wide illustration will letterbox rather than distort. Much above 48px and markers start to overlap each other in a dense city.

Default

36 px

Appears when

Only applies to uploaded marker artwork.

Which point of the artwork sits on the location's coordinate.

Artwork shaped like a pin should stand on its tip, so the place it points at is the place it means. Artwork shaped like a badge or a logo should be centred, the way a dot is.

Default

Bottom edge (like a pin)

Choices

Bottom edge (like a pin), Centre (like a dot)

Appears when

Only applies to uploaded marker artwork.

Matches each pin to its position in the list, so a visitor can connect what they see on the map to what they are reading.

Default

On

Appears when

The layout has no map, so there is nothing to configure here.

Clicking a pin scrolls the matching entry into view and highlights it, instead of only opening a popup.

Default

On

Appears when

The layout has no map, so there is nothing to configure here.

Drops a distinct pin where the visitor searched, so they can see what the distances are measured from.

Default

On

Appears when

There is no search point to mark until "Search near a place" is turned on.

Keeps the map showing only what is in the list. Off leaves distant pins visible for context.

Default

On

Appears when

Only applies once visitors can choose a search radius.

Moving the clicked pin toward the bottom leaves room for its popup above it, instead of the popup running off the top of the map.

Also applies when a visitor clicks a result in the list, since both should land the same way.

Default

Bottom of the map

Choices

Centre of the map, Bottom of the map, Do not move the map

Appears when

The layout has no map, so there is nothing to configure here.

Where the list sits relative to the map.

Side by side needs a wide container; list below works in narrow columns and on mobile.

Default

List below the map

Choices

List left of the map, List right of the map, List below the map, Grid below the map, List only, no map, Grid only, no map, Map only, no list

Use a percentage to fill the container it is embedded in, or a fixed value like 560px to cap it.

Filling the container also gives the map more room.

Default

100%

How tall the scrolling result list is, in pixels.

Default

360 px

Appears when

The layout is map-only, so there is no result list.

Aligns the name, address and details inside each result card.

Left reads fastest for addresses. Centre suits a short, symmetrical card where the name is the point and the address is secondary.

Default

Left

Choices

Left, Centre

Appears when

The layout is map-only, so there is no result list.

How the result a visitor has chosen is marked out from the rest.

The border is the quietest and is what every locator has used so far. A stripe down the leading edge survives a long list where a thin border blurs into its neighbours, and a tint is the strongest of the three but leans on colour alone, so it fades for anyone who does not see that colour well.

Default

Accent border

Choices

Accent border, Accent stripe, Tinted background

Appears when

The layout is map-only, so there is no result list.

Draws a border around the whole locator and its map.

Useful when the locator sits directly on a coloured page section and would otherwise bleed into it. It uses the same border colour and weight as the cards, so it stays part of the same system.

Default

No frame

Choices

No frame, Bordered

Whether the scrolling result list uses the browser's own scrollbar or a themed one.

The list already fades its top and bottom edges to show there is more to scroll, which is why the default leaves the scrollbar alone: browsers disagree about styling it, and the ones that do it worst are the ones that show it permanently. Choose themed when the design needs the bar itself to match.

Default

Browser default

Choices

Browser default, Match the text colour

Appears when

The layout is map-only, so there is no result list to scroll.

Where the distance sits inside a result card.

With the details, distance reads as another fact about the place. Under the buttons it reads as a footnote to the whole card, which suits a card whose action is the point and whose distance is a tiebreak between two places that both work.

Default

With the details

Choices

With the details, Below the buttons

Appears when

The layout is map-only, so there is no result card.

How much of the width the result list takes when it sits beside the map.

Default

40 %

Appears when

The list only shares a row with the map in the side-by-side layouts.

Sets how many result cards appear across when a grid layout is selected.

Default

3 columns

Appears when

Grid columns only applies to grid layouts.

Gives visitors one control that clears the search and every filter at once.

Default

Off

Icons alone are compact but less obvious. Icons with text is the safest for a general audience.

Default

Text only

Choices

Text only, Icons and text, Icons only

How a location's details are arranged in the popup that opens from a map pin. Two columns also widens the popup, since two narrow columns read worse than one.

Default

Single column

Choices

Single column, Two columns

Match the device sends iPhone and iPad visitors to Apple Maps and everyone else to Google Maps.

This avoids sending someone to an app they may not have installed.

Default

Always Google Maps

Choices

Always Google Maps, Always Apple Maps, Match the visitor's device

A new tab keeps the visitor on your page. Same tab sends them away from the locator entirely.

Default

In a new tab

Choices

In a new tab, In the same tab

Showing it on the map keeps the visitor inside the widget.

Linking to the website sends them off to that location's own page instead.

Default

Show the location on the map

Choices

Show the location on the map, Open the location's website, Do nothing

Adds a print control to the directions panel.

Default

Off

Reformats imported US and Canadian numbers to (555) 555-0100. Off keeps exactly what was in your file.

Only North American numbers are reformatted, because their digits alone determine the format. International numbers, extensions and letter numbers like 1-800-FLOWERS are left exactly as written rather than reshaped by a guess.

Default

Off

Appears when

Shown when the phone field is included in the public layout.

Converts ALL CAPS or all lowercase names, addresses and cities to title case on import.

Only applied when a value is entirely upper or entirely lower case. Anything with deliberate mixed casing — McDonald's, iHop, LATAM — is left untouched, so switching this on will not flatten real brand names.

Default

Off

Flags an imported row when a location with the same name and address already exists, and leaves it unticked so it is not imported twice.

Flagged rows are still shown and can be ticked back on — dedup errs toward letting you decide rather than silently dropping data.

Default

On

The file type used when you download your locations.

Default

CSV

Choices

CSV, JSON

Automatic restores the leading zeros spreadsheets strip from US ZIP codes, so 01234 does not import as 1234.

Only applied to US rows with a 3 or 4 digit value, so a genuine four-digit postcode elsewhere (Australia, South Africa) is never padded.

Default

Automatic

Choices

Automatic, Leave as imported