Documentation

Option Sets and Lists

An option set is a predefined list of key-value pairs that powers dropdown fields in your content models. When you need editors to choose from a fixed set of values — a color theme, a layout variant, a content category — you define the choices as an option set and connect it to a dropdown field.

This page covers how option sets work, how they connect to dropdown fields, accessing option sets through the content API, and how to decide between option sets and entry models for taxonomy.

What Is an Option Set

An option set is a simple list of label-value pairs managed at the site level. Each pair consists of a human-readable label that editors see in the dropdown and a machine-readable value that gets stored and delivered through the API.

For example, a "Button Style" option set might contain:

Label Value
Primary primary
Secondary secondary
Outline outline
Ghost ghost

The editor sees "Primary", "Secondary", "Outline", and "Ghost" in the dropdown. The stored value — what your templates and frontend code receive — is primary, secondary, outline, or ghost.

Option sets are defined once and can be used by dropdown fields across any number of models. The "Button Style" set can power a dropdown on a CTA block, a hero block, a card block, and anywhere else you need a button style choice. Changes to the option set — adding a new style, renaming a label, removing an option — are reflected everywhere the set is used.

Key-Value Pairs

Each item in an option set is a pair: a label and a value.

Labels are for editors. They appear in the dropdown UI and should be clear, descriptive, and written in natural language. "Two Columns", "Dark Background", "Left Aligned" — these are labels.

Values are for code. They're stored in the content record and delivered through the API. Values are typically lowercase, hyphenated or snake_cased strings that your templates and frontend code use for logic and styling: two-columns, dark-bg, left.

Keeping labels and values separate means you can rename what editors see without breaking your templates. If you change the label from "Two Columns" to "Side by Side", the stored value two-columns stays the same and nothing in your code needs to change.

Using Option Sets in Dropdown Fields

To use an option set, you add a dropdown field to a model and connect it to the option set. The field then presents the option set's labels as choices in the editor.

A dropdown field connected to an option set stores the selected value (not the label) in the content record. When an editor selects "Primary" from a button style dropdown, the content record stores primary. When your template or frontend reads that field, it gets the string primary and can use it for CSS classes, conditional rendering, or any other logic.

Dropdown fields can be added to page models, entry models, and block models. This makes option sets available anywhere you need a constrained choice — layout variants on a block, content categories on a page, theme selections on a site settings entry.

Common Uses

Layout control — Let editors choose between layout variants for a block. A features section might offer "grid", "list", or "carousel" layouts. The block template reads the selected value and renders the appropriate layout.

Theme and styling — Let editors select color themes, background styles, or spacing options. A section block might offer "light", "dark", or "brand" themes, and the template applies the corresponding CSS class.

Content classification — Let editors tag content with a type or category. A blog post might have a "Post Type" dropdown with values like "article", "tutorial", "announcement", or "case-study".

Configuration flags — Let editors toggle behavior through predefined options. A CTA block might have a "Size" dropdown with "compact" and "full-width" values, or an "Animation" dropdown with "none", "fade-in", and "slide-up".

Centralized Taxonomy

Option sets serve as a lightweight taxonomy system. When you need a consistent set of categories, tags, or classifications across your site, defining them as an option set ensures editors always choose from the same list.

Without option sets, you'd rely on free-text fields, which inevitably leads to inconsistency — one editor types "Case Study", another types "case-study", a third types "Case study". A dropdown backed by an option set eliminates this problem. The values are predefined, consistent, and controlled.

Because option sets are managed centrally, adding a new taxonomy value — a new category, a new tag, a new classification — is a single change that immediately appears in every dropdown connected to that set. You don't need to update each model individually.

Accessing Option Sets via API

Option sets with a handle can be retrieved directly through the content API using the getOptions() method. This is useful when your frontend needs the full list of options — for building filter interfaces, rendering navigation based on categories, or populating client-side dropdowns.

To make an option set available through the API, assign it a handle in the admin UI. The handle is the identifier you pass to getOptions().

const categories = client.getOptions('categories');
// [
//   { label: 'Technology', value: 'tech' },
//   { label: 'Design', value: 'design' },
//   { label: 'Business', value: 'business' },
//   { label: 'Marketing', value: 'marketing' }
// ]

This is separate from how option values appear in content records. When a page or entry has a dropdown field, the API response for that record includes the selected value as a string. The getOptions() method gives you the complete list of available options, which is what you need when you want to render all choices rather than just the one that was selected.

A practical example: a blog has a "Category" dropdown backed by a "Categories" option set. Individual blog posts return their selected category value in the API response (post.category → 'design'). But your category filter sidebar needs the full list of categories to render all the filter buttons. That's where getOptions('categories') comes in.

In Templates

In the site builder, option sets are accessible through the template context. You can iterate over an option set to render navigation, filter lists, or any UI that needs the full set of choices. The selected value on a content record is available through the item variable, while the complete option set is available through the global options accessor.

→ Content API → Template Context and Data Access

Option Set vs Entry Model

Option sets and entry models can both serve as sources of taxonomy or categorization, but they solve different problems. The choice depends on the complexity of the data and how it's used.

Use an option set when:

  • The data is a simple label-value pair with no additional fields. A list of color themes, layout options, or content categories where each item is just a name and a code.
  • The list is relatively stable and managed by administrators. Option sets are configuration, not content — they define the available choices, not something editors create on the fly.
  • You need a dropdown in the editor. Option sets are designed to power dropdown fields with minimal setup.

Use an entry model when:

  • Each item needs additional fields beyond a label and value. A "Category" with a name, description, icon, and featured image is too complex for an option set — it needs its own model with multiple fields.
  • Editors need to create and manage items independently. Entry models appear in the content list where editors can add, edit, and delete entries. Option sets are managed in the modeling layer, typically by administrators.
  • The data will be referenced with its full structure. Entry references resolve to the complete entry object in API responses, giving your frontend access to all fields. Option set values are just strings.
  • Items need their own visual representation. Entries can have templates in the site builder. Option sets are purely data.
Capability Option Set Entry Model
Data structure Label + value only Multiple typed fields
Managed by Administrators (modeling layer) Content editors (content list)
Used in editor as Dropdown selection Reference field selection
API response shape String value Full object with all fields
Own template in site builder No Yes
Best for Simple choices, flags, variants Rich taxonomy, complex relationships

In practice, many sites use both. Option sets handle simple choices like layout variants, button styles, and theme selections. Entry models handle rich taxonomy like authors, categories with descriptions, and any classification that carries its own content.

What's Next

  • Content Field Types — The full set of field types including dropdown, reference, and other relational fields.
  • Page Models — Routable content types that use option sets in dropdown fields.
  • Entry Models — Structured content for rich taxonomy and reusable data.
  • Block Models — Composable content components where option sets control layout and style variants.
  • Content API — REST and GraphQL endpoints for retrieving option sets and content.