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
FeaturesFinder Builder

Finder Builder

The Finder Builder is the central editor in DropAFinder. You’ll spend most of your time here. This page tours every section in the order they appear in the sidebar, explains what each section is for, and notes the most common decisions you’ll make.

Layout

When you open a finder at /app/finders/{id}, you see three regions:

  1. Sidebar (left) — a grouped list of every section you can edit.
  2. Content (center) — the controls for the currently-selected section.
  3. Live Preview (right) — your finder rendered as a visitor would see it, updating as you edit.

🟡 [SCREENSHOT: Annotated full-screen capture of the Finder Builder. Mark the three regions, the section nav, and the Save / Discard / Undo controls.]

The Live Preview reflects unsaved changes. Saving is explicit — your visitors don’t see your edits until you save (and even then, a CDN cache refresh takes a few minutes; see Caching).

Section groups

The sidebar groups sections into four phases of building a finder:

  • Setup — the bones (title, attached locations and categories, fields, refinements)
  • Look & Feel — visual design (theme, typography, shape, layout, map style, language)
  • How it Behaves — runtime knobs (geolocation, default sort, click handlers)
  • Launch — embed snippet and authorized URLs

A new finder generally moves through these top-to-bottom on first creation. Returning to an existing finder, you’ll usually jump straight to the section you need.

Setup sections

Title and basics

Set the human name of the finder and an internal description. Neither is shown to visitors directly, but the title appears on the embed snippet modal and helps you identify the finder in lists.

Locations and Categories

Choose which Locations and Categories supply data to this Finder. You can attach Locations directly, attach one or more Categories (which bring along all their member Locations), or mix both. Most Finders draw from one or more Categories; attaching Locations directly is useful for small, static lists or for locations that don’t fit any Category grouping. See Categories.

Fields

Choose which fields appear on each location result card and where they sit. The Field Composer is a drag-and-drop editor that maps built-in fields (address, phone, distance, hours) and any Custom Fields you’ve defined into six zones on the card. Field Composer is available on eligible plan tiers.

Refinements

Choose which filters and facets your visitors see. The default set covers the common cases (radius from current location, country, tag); you can add custom-field-based refinements once you’ve defined Custom Fields. Reorder by drag-and-drop. See Refinements for the full reference.

Content

The text wrapper around the data: heading, intro, CTA, empty state. See Content.

Look & Feel sections

This is where most customization happens. Each Look & Feel section has its own page in this documentation set:

  • Theme & colors — pick from 16 curated presets, or override individual color tokens. The Live WCAG checker keeps you within accessibility guarantees.
  • Typography — body and heading fonts, base size.
  • Shape — corner radius via six presets and an optional per-element editor.
  • Layout — choose from 9 layout tiles (map-first, list-first, split, etc.).
  • Map style — provider (TomTom / Mapbox / HERE / OSM) and visual variant.
  • Language & copy — primary language plus per-string overrides.

💡 Tip: Don’t customize colors until you’ve spent a few minutes with the curated themes. All 16 are designed for legibility and brand fit, and they cover most use cases.

🟡 [SCREENSHOT: Look & Feel section nav expanded showing all six items with the active one (Theme) highlighted.]

How it Behaves

Runtime toggles that change the visitor experience. The most-used controls:

  • Geolocation prompt — ask for location on load (best for “near me” finders), never ask, or fall back to IP-based location.
  • Default sort — distance from visitor, alphabetical, or custom.
  • Click behavior — what happens when a visitor clicks a location card (open detail panel, navigate to external URL, do nothing).
  • Auto-zoom — whether the map re-frames when filters change.

See Behavior for the full list.

Launch

The final section before going live:

  • Embed snippet — the <script> tag to paste into your website, with the finder’s public token already filled in.
  • Authorized URLs — domains allowed to render this finder. Add your production domain plus any staging environments. See Authorized URLs.

⚠️ Warning: A finder with no Authorized URLs may render only on configured-as-default origins (typically localhost). Don’t forget to add your production domain before launch.

Save, discard, and undo

The top bar of the builder has three actions:

  • Save — commits all pending changes. Updates propagate to the CDN within ~5 minutes.
  • Discard — reverts unsaved changes back to the last saved state.
  • Undo / Redo — step backwards or forwards through your edit history within the current session. Undo history resets when you save or reload.

💡 Tip: Heavy theme work is much easier with undo than with manual revert. Experiment freely; you can always step back.

Live Preview

The right rail Live Preview embeds the same widget that runs on your website, but in a special preview mode that uses your unsaved changes instead of the published version. It also disables analytics so your edits don’t show up in your visitor metrics.

🟡 [SCREENSHOT: Live Preview rail with the same finder shown twice — top half showing the published version, bottom half showing the preview-mode version with an unsaved color change applied.]

If your edits don’t appear in Live Preview, the most common cause is that the preview is loading from the CDN instead of using local state — refresh the builder page and try again.

Edge cases and limitations

  • Save conflicts. If two people edit the same finder simultaneously, the last save wins. There is no merge UI today.
  • Long titles. Finder titles longer than ~60 characters truncate in the visitor list view.
  • Many locations. Finders with thousands of locations perform best when Categories are used to pre-filter the dataset rather than attaching the full Workspace’s Locations directly; aim to keep the rendered list under ~500.
  • Custom-field-based refinements. A refinement built on a Custom Field will silently disappear if you delete that Custom Field definition. Recreate the refinement after re-adding the field.

Where to next

Field ComposerLanguage and copy