Documentation

Variants & fallbacks

How variant overrides are stored, how groups behave, and exactly which override wins when several could apply. For the high-level concepts, start with Personalization.

Variants & groups

A variant is a named audience segment (Returning visitor, Mobile, Newsletter). Variants can stand alone or live inside a group, and every group has a select type:

single	Mutually exclusive — activating one variant deactivates its siblings. Use for states a visitor can only be one of: Device: Mobile / Desktop, Plan: Free / Pro.
multi	Independent toggles — any number can be active together. Use for overlapping traits: Source: Newsletter, Product Hunt, Feature flags.

Create and reorder them right in the entry editor's variant bar (+ Variant, + Group) or in Settings → Space → Personalization. The catalog is space-wide — every entry shares the same variants; only the overrides are per-entry.

Drag pills and groups to reorder them. Order isn't cosmetic — it's the priority order used to break ties during fallback (below).

How overrides are stored

The Default layer is the entry's full data. Each variant combination you edit stores only a flat map of changed paths — nothing is duplicated:

"personalization": {
  "returning":        { "title": "Welcome back!" },
  "mobile+returning": { "title": "Hi again 👋", "hero.image": "…" }
}

Combination keys are the sorted variant ids joined with + — so an override for Mobile + Returning applies only when both are active (subject to fallback, below).

Array items that carry a stable id are addressed by id, not by position (panels[id:hero-1.headline]). Reordering the array in the default layer doesn't break the override, and overrides pointing at a deleted item are skipped instead of resurrecting it.

Fallback logic

The space-level fallback toggle decides what happens when a visitor's active variants don't exactly match a stored combination:

Fallback off — exact match only

Only the override stored for the exact active combination applies. Active mobile+returning uses the mobile+returning override or falls straight back to the default layer — the standalone mobile override is ignored.

Fallback on — layered resolution

Every stored combination that is a subset of the active variants applies, layered least-specific first so the most specific value wins per field. Fields a deeper combo doesn't touch keep the shallower value.

With fallback on and mobile + returning active:

default layer                 title: "Hello"      cta: "Sign up"   hero: "a.png"
"mobile"                      —                   cta: "Tap to start"  —
"returning"                   title: "Welcome back!"   —              —
"mobile+returning"            title: "Hi again 👋"     —              —

resolved (most specific wins per field):
  title: "Hi again 👋"        ← mobile+returning
  cta:   "Tap to start"       ← mobile
  hero:  "a.png"              ← default

When two combinations are equally specific (e.g. mobile vs returning, both single-variant), the tie is broken by the canonical variant order — the pill order you arranged by dragging. Earlier wins.

Cleaning up stale overrides

Deleting a variant or group removes the definition but intentionally leaves its stored overrides behind — deleting is reversible, silent data loss isn't. The editor's Cleanup button lights up (amber) whenever overrides reference deleted variants or fields that no longer resolve; one click removes exactly those stale entries and nothing else.

Publishing & serving

Overrides follow the same draft/publish cycle as the rest of the entry: edits stay in the draft layer until you publish, and the public API only ever serves the published override layer. The API response also carries the catalog's fallback flag and order, so client-side resolution behaves identically to the server — see API Reference → Personalization.