Tags and Custom Fields

Two ways to add structured information to your Locations. Tags are free-form labels you can apply ad-hoc; Custom Fields are workspace-defined typed attributes that every Location carries. They serve different needs, and most workspaces use both.

For the underlying concept, see Concepts. For the Locations panel itself, see Locations.

When to reach for which

💡 Tip: If you’re not sure, start with Tags. They’re cheaper to add and remove. Promote a Tag to a Custom Field when you find yourself wanting type validation (e.g., “this should always be a phone number”) or visitor-facing rendering.

Tags

What a Tag is

A free-form, Workspace-scoped label. Tags have a name (what you type and what visitors see) and a slug auto-generated from the name (used in URLs and refinement filters). Tags are not typed — there’s no “this tag is a number.” They’re labels, full stop.

Adding a Tag to a Location

In the Location editor:

1. Open the Tags input
2. Type a name; existing matching tags appear as suggestions
3. Press enter on a suggestion to apply it; press enter on a new name to create it
4. Repeat for as many tags as you want
5. Save the Location

🟡 [SCREENSHOT: Location editor with the Tags input partly populated, suggestions dropdown visible, and one new tag in mid-creation.]

Bulk-applying Tags

In the Locations panel:

1. Select multiple Locations via checkboxes
2. Click Add tag in the bulk-action bar
3. Pick or create the tag
4. The tag is applied to every selected Location

Bulk Remove tag works the same way.

Slug behavior

The slug is generated from the name by lowercasing, replacing spaces with hyphens, and stripping non-URL-safe characters. Featured Stores → featured-stores.

If you rename a Tag, its slug regenerates. Any refinement that depended on the old slug continues working because refinements bind to the Tag id, not the slug — but URL deep-links that include the slug will break.

🔴 [NEEDS CLARIFICATION: Confirm whether refinements bind to slug or id. The above assumes id; if it’s actually slug-based, the rename caveat changes materially.]

Tags as Refinements

To let visitors filter by Tag, configure a Tag refinement under the Finder Builder’s Refinements section. The refinement auto-populates from the Tags present in your attached Locations.

A common pattern:

• Create Tags like flagship, popup, outlet
• Apply them to the relevant Locations
• Add a Tag refinement to your Finder
• Visitors see chips matching your Tags

Edge cases

• Tags are not deleted automatically. A Tag with zero associated Locations still exists in the Workspace. To clean up, manage Tags from the Tags panel in the sidebar.
• Tag names are case-preserved but slug-collapsed. Featured and featured create one Tag (because both slug to featured); the name keeps whichever was typed first.
• Renaming affects every Location that uses the Tag.
• There is no Tag hierarchy — Tags are flat, not nested.

Custom Fields

What a Custom Field is

A Workspace-level definition that adds a typed attribute to every Location. Defining a Custom Field once gives every Location (existing and future) a slot for that attribute’s value.

A Custom Field has:

• A name (visible in the Location editor and, when configured, on the visitor-facing detail card)
• A type (text, number, etc.)
• A required flag (whether Locations must have a value)
• An order index (where it appears in the Location editor among other Custom Fields)

Defining a Custom Field

From the sidebar, open Custom Fields and click Add field:

1. Enter a name (e.g., Hours, Open on Sundays, Phone)
2. Pick a type
3. Decide whether values are required
4. Save

The new field immediately appears as an input on every Location’s editor. Existing Locations have empty values for the new field until you populate them.

🟡 [SCREENSHOT: Custom Fields panel listing four fields with their types, required flags, and order, plus the “Add field” button.]

Field types

If a type you need isn’t listed, use text and accept that values won’t be validated. File a feature request if the missing type is important to your use case.

Setting Custom Field values on a Location

The Location editor renders one input per Custom Field. Inputs match the field’s declared type — select fields show a dropdown, number fields show a numeric input, textarea fields show a multi-line editor, and so on.

For bulk-setting (e.g., setting a default value for many Locations at once), use the bulk-edit flow on the Locations panel.

Where Custom Fields surface to visitors

Three places:

1. Location result card — you control which fields appear on the card and where they sit using the Field Composer inside the Finder Builder. Fields can be toggled on or off per Finder independently of each other.
2. Refinements — a Custom Field can drive a Refinement. The visitor control rendered depends on the field type (selects get dropdowns, numbers get range sliders, etc.).
3. Search-as-you-type — text Custom Fields can be searchable as part of the visitor’s search input (configurable in Refinements).

Reordering Custom Fields

The order index controls where each field appears in the Location editor. To reorder, drag rows in the Custom Fields panel; the order updates immediately and applies to every Location’s editor.

🟡 [SCREENSHOT: Custom Fields panel with one row mid-drag, showing the drag handle on the left and the new position highlighted.]

The order in the panel is also the default order in the Field Composer’s field library. The Field Composer controls the final rendering order on the visitor-facing card independently.

Renaming, retyping, deleting

• Rename: changes the display name everywhere. Existing values are preserved.
• Change type: risky. Existing values may not validate against the new type. Recommendation: if you really need a different type, define a new field, copy values manually, then delete the old field.
• Delete: removes the field definition and every value across every Location. Irreversible.

⚠️ Warning: Deleting a Custom Field also removes it from the Field Composer on every Finder that used it, and breaks any Refinement built on that field — those Refinements disappear from visitor UIs on next load. Recreate the Refinement after re-adding the field.

Tags vs. Custom Fields side-by-side

Where to next

• The Locations themselves: Locations
• Choosing which fields appear on the visitor card: Field Composer
• Filtering visitors’ view by these attributes: Refinements
• Conceptual overview of all data primitives: Concepts
• Bulk-loading data with Custom Field values: Add locations