These docs are a work in progress and may not be fully up to date. Some pages may contain internal notes for our team.
Skip to Content
FeaturesRefinements

Refinements

Refinements are the filters and facets your visitors use to narrow down the location list. The Refinements section of the Finder Builder lets you choose which refinements appear, in what order, and with what defaults. This page covers configuration; for the visitor experience, see the relevant section of Finder Builder.

What a refinement is

A refinement is any control that filters the visible Locations on the visitor’s screen. There are several shapes:

  • Filter — a binary include/exclude (e.g., “only show open locations”)
  • Facet — a multi-select pick from a known list (e.g., “tags: warehouse, retail, popup”)
  • Range — a numeric or distance bound (e.g., “within 25 km”)
  • Search-as-you-type — a freeform text search that filters by name or address

The visitor’s UI shows refinements as a row of dropdowns, chips, or sliders depending on the refinement type and your layout choice.

Where to find it

In the Finder Builder, open Setup in the sidebar and click Refinements.

🟡 [SCREENSHOT: Refinements page in the Finder Builder showing the configured refinement list (Radius, Country, Tag) with one row being dragged to reorder.]

Built-in refinements

Three refinements ship with every Finder; you can enable or disable each:

Radius from current location

  • Type: range slider with preset distances (5 / 10 / 25 / 50 / 100 km, or miles)
  • Visitor experience: a slider or dropdown to limit results to within N units of their current location
  • Requires: visitor’s geolocation (browser prompt) or IP fallback
  • Best for: any “near me” use case

Country

  • Type: facet, single-select
  • Visitor experience: a dropdown to pick a country
  • Auto-populated: from the countries present in your attached Locations
  • Best for: multinational finders where visitors care about country

Tag

  • Type: facet, multi-select
  • Visitor experience: a row of chips, each toggling a tag on/off
  • Auto-populated: from the Tags present in your attached Locations
  • Best for: any taxonomic distinction you’ve already encoded as Tags

Custom-field-based refinements

Beyond the built-ins, you can create a refinement on any Custom Field you’ve defined for the Workspace.

How to add one

  1. On the Refinements page, click Add refinement
  2. Select Custom field
  3. Pick the field
  4. Pick the refinement type (the available types depend on the field’s data type — booleans get a toggle, numbers get a range, text gets a facet of distinct values, etc.)
  5. Configure label, default state, position
  6. Save

The refinement appears in the visitor UI immediately on next load.

🔴 [NEEDS CLARIFICATION: Confirm exact mapping from Custom Field type → available refinement types. The above is the most likely shape, but the precise type-to-type mapping should be enumerated. Affects what users can actually do with their custom fields.]

When to use Custom Field refinements

Whenever a “filter by …” question matters to your visitors and the answer lives in a Custom Field. Common patterns:

  • “Open on Sundays” — boolean Custom Field → toggle refinement
  • “Drive-thru available” — boolean Custom Field → toggle refinement
  • “Type” (e.g., warehouse / retail / popup) — single-select Custom Field → dropdown refinement
  • “Service offered” (visitor cares about specific service) — multi-select or comma-separated text Custom Field → facet refinement

If you want to filter on something that isn’t yet a Custom Field, define the field first (see Tags and custom fields), populate values on your Locations, then come back here to add the refinement.

Ordering and grouping

Refinements appear in the visitor UI in the order you list them. Drag rows on the Refinements page to reorder.

💡 Tip: Put high-impact refinements first. “Radius from current location” is almost always the highest-impact for a near-me finder; put it first. Less-used refinements go later.

🔴 [NEEDS CLARIFICATION: Confirm whether refinements can be grouped (e.g., a “Filter by” group and an “Hours” group). The codebase digest doesn’t surface a grouping mechanism in the standard refinement set; if grouping exists, this section needs documenting it.]

Defaults and “applied on load”

Each refinement has a default state. By default, refinements start empty — no filter applied, all Locations visible.

You can configure a refinement to be applied on load, meaning visitors see filtered results before they touch anything:

  • A “Country” refinement defaulted to the visitor’s geolocated country
  • A “Radius” refinement defaulted to 25 km
  • A “Tag” refinement defaulted to a specific tag

⚠️ Warning: Applied-on-load refinements can hide most of your data from a casual visitor. If a visitor’s geolocated country has no Locations, they see an empty list; if your default radius is 5 km and your visitor is in a sparse area, they see nothing. Test from outside your headquarters.

Mobile presentation

On narrow screens, refinements collapse into a “Filter” button that opens a panel. The visitor toggles refinements in the panel, then returns to the list.

You don’t configure mobile refinements separately — they derive automatically from your desktop refinement list. Reordering on the desktop list also reorders the mobile panel.

🟡 [SCREENSHOT: Mobile preview of the visitor-facing widget with the “Filter” button collapsed at the top, and a second screenshot showing the panel open after tap with the refinements visible.]

Search-as-you-type

If your finder has many Locations, an opt-in search input above the list lets visitors filter by name or address as they type. This is separate from the address-autocomplete search bar; it filters the already-loaded list rather than searching for places.

Enable it from the Refinements page; configure placeholder text and which fields it searches.

Advanced: refinement schema

For finders with non-standard requirements (e.g., a refinement that filters by combination of two Custom Fields, or that drives map clustering behavior), DropAFinder exposes an advanced_refinements configuration on the Finder. This is a JSON object you edit directly via the Advanced refinements page; it’s not for casual use.

🔴 [NEEDS CLARIFICATION: Schema of the advanced_refinements JSON. Affects whether to document this page in detail or punt to a “talk to support” recommendation.]

Edge cases and limitations

  • Refinements built on a deleted Custom Field disappear silently. If you delete a Custom Field that a refinement depends on, the refinement is removed from the visitor UI on next load. Recreate the refinement after re-adding the field.
  • Tag refinements show all Tags in the Workspace, not just those on attached Locations. This means a visitor may see a tag option that filters to zero results. Recommendation: use Tags consistently, or scope a Finder to a Set that has only the relevant Tags.
  • Distance refinements require geolocation. If the visitor declines the browser prompt and IP-based fallback is also disabled or unavailable, the radius refinement renders disabled with a hint to enable location.
  • Combining many refinements can return zero results. Visitors don’t always notice — consider a clear empty state with a “clear filters” action. Configure that under Content.
  • No conditional refinements. You can’t show a refinement only when another refinement is active. If you need that, the workaround is to use multiple Finders, each scoped to a different subset of Locations.

Where to next

Map styleSearch