Variants

Variants let you serve different content to different audiences from the same record. Show mobile users a simplified layout, VIP customers exclusive offers, or regional users localized promotions — all without duplicating records.

Overview

A variant is an alternative version of your content that displays when certain targeting conditions are met. Each record can have multiple variants:

Homepage
  -- Default variant (shown to everyone else)
  -- Mobile variant (simplified for small screens)
  -- VIP variant (exclusive offers)
  -- Holiday variant (seasonal content)

When a visitor requests content, Foir evaluates the targeting rules on each variant against the provided context (device, segment, market, etc.). The first matching variant is returned. If none match, the default variant is used.

Variants are only available on models with the variants capability enabled.

Key Concepts

• Default variant — Every record has a default variant that acts as the fallback when no other variant matches
• Targeting rules — Conditions that determine when a variant is shown (device type, authentication status, custom contexts)
• Priority — A numeric value that controls evaluation order; higher priority variants are checked first
• Independent publishing — Each variant has its own publishing state and version history

Three Levels of Variation

Variants apply at three levels of granularity. Use the smallest level that gets the job done:

Block-level variants are the most useful for translation: the structural skeleton of the page stays the same across locales, but every prose segment, hero headline, and CTA label varies independently. Each item in the resolved content output (structured blocks and prose segments) is a variantable unit, so you don’t need to duplicate the whole document just to change one block.

Block-level variants swap a whole block’s data — they don’t subset individual fields within a block. A block is a unit; if you need to vary one field of a block, swap the block.

In the Admin

Creating a variant

1. Open any record that belongs to a model with variants enabled
2. Click the Variants dropdown at the top of the editor
3. Click Add Variant
4. Configure:
   • Name: “Mobile Version”
   • Key: mobile (used in APIs)
   • Targeting: Set rules for when this variant should display
   • Priority: Higher values are checked first
5. Edit the variant’s content
6. Publish when ready

Using the Variant Catalog

For targeting rules you reuse across multiple records:

1. Go to Settings > Variant Catalog
2. Create reusable targeting rules (e.g., “VIP Customers”, “Mobile Users”)
3. When creating a variant, select from the catalog instead of defining custom rules

See Variant Catalog for details.

Targeting Rules

Targeting rules determine which variant to show. Rules are built from conditions that can be combined with AND/OR logic.

Available conditions

Device and Platform

• Device is mobile, tablet, or desktop
• Platform is web, iOS, or Android

Authentication

• User is logged in or anonymous

Custom Contexts (you configure these)

• Market (UK, US, EU, etc.)
• Customer segments (VIP, first-time, returning)
• Any custom dimension you define

Combining rules

Show to VIP mobile users:

• Segment is VIP AND Device is mobile

Show to UK or US visitors:

• Market is UK OR Market is US

Variant Priority

When multiple variants could match a request, priority determines the winner. Variants are evaluated from highest priority to lowest, and the first match wins.

Recommended priority ranges

Publishing Variants

Each variant publishes independently:

• Edit the VIP variant without affecting the default
• Publish mobile changes while VIP stays in draft
• Schedule different variants for different dates

Version History

Each variant maintains its own version history:

1. Make changes (auto-saved as draft)
2. Preview before publishing
3. Publish when ready
4. Roll back to a previous version if needed

Via the CLI

List variants for a record

foir records variants rec_abc123

Create a variant

foir records create-variant --data '{
  "recordId": "rec_abc123",
  "variantKey": "mobile",
  "name": "Mobile Version",
  "data": {
    "title": "Mobile Title",
    "content": "Simplified content for mobile."
  }
}'

Via the API

Content resolution with contexts

Pass context values when querying to trigger variant resolution:

query {
  recordByKey(modelKey: "page", naturalKey: "homepage") {
    resolved(
      locale: "en-US"
      contexts: { device: "mobile", market: "us" }
    ) {
      content
      variant {
        id
        variantKey
        matchedContexts {
          key
          value
        }
      }
      resolvedWith {
        locale
        contexts
      }
    }
  }
}

The response tells you which variant was selected and why, via the variant and resolvedWith fields.

Use preview: true to resolve against draft content instead of published versions.

Common Use Cases

Mobile optimization

Create a mobile variant with shorter headlines, fewer images, simplified navigation, and larger tap targets.

Regional content

Create market variants with local currency and pricing, region-specific offers, localized images, and local contact information.

Customer segments

Create segment variants with VIP-exclusive content, first-time visitor onboarding, returning customer promotions, and loyalty tier benefits.

A/B testing

Create test variants with different headlines, alternative CTAs, layout variations, or image options. See Experiments for structured A/B testing with traffic allocation and goal tracking.

Best Practices

• Always keep a meaningful default variant. It serves as the fallback when no targeting rules match.
• Keep targeting rules simple. Complex rules are harder to debug and maintain.
• Use the Variant Catalog for rules shared across multiple records, so updates propagate automatically.
• Test thoroughly by previewing with different context values before publishing.
• Use clear variant names and descriptions so your team understands the purpose of each.