---
title: Enum field
description: Display one or more values from a declared option set.
---

An enum field declares the complete set of accepted values and the label for
each value. An option can also carry a semantic tone. The renderer shows the
option label instead of the stored value.

## API

```ts
fields.enum<Name extends string, const Choices extends readonly EnumOption[]>(
  name: Name,
  choices: Choices,
  options?: EnumFieldOptions
): EnumFieldBuilder<Name, Choices>
```

| Option           | Input                           | Result                                   |
| ---------------- | ------------------------------- | ---------------------------------------- |
| `label`          | `string`                        | Sets the text shown for the field.       |
| `description`    | `string`                        | Adds supporting text for the label.      |
| `displayVariant` | `badge` or `text`               | Selects the read-only presentation.      |
| `inputVariant`   | `select`, `radio`, `checkboxes` | Selects the form control.                |
| `cardinality`    | `one` or `many`                 | Selects one value or an array of values. |

`getOptionValues()` and `getOptionLabels()` return the choice values and
labels in declaration order. `configure(options)` returns a configured clone.
`clone()` returns an independent copy with the same choices and options.

Each choice requires a `value` and `label`. Its optional `tone` can be
`neutral`, `info`, `success`, `warning`, or `danger`.

## Basic enum field

<BacklitExample path="fields/enum/basic" view="detail" />

## Description

Use a description to explain the meaning or selection rule for the option set.

<BacklitExample path="fields/enum/description" view="detail" />

## Option tones

A tone gives an option semantic meaning. It is most visible when the field uses
the `badge` display variant.

<BacklitExample path="fields/enum/option_tones" view="detail" />

## Display variants

Use `text` to show option labels as text. Use `badge` to show each label as a
status badge.

<BacklitExample path="fields/enum/display_variants" view="detail" />

## Input variants

Use `select` for a compact control and `radio` for a visible single-choice set.
Use `checkboxes` with `many` cardinality for multiple choices.

<BacklitExample path="fields/enum/input_variants" view="detail" />

## Cardinality

Use `one` for one stored value. Use `many` for an array of stored values. If you
do not set cardinality, the field uses its single-value behavior.

<BacklitExample path="fields/enum/cardinality" view="detail" />

## Option helpers

`getOptionValues` and `getOptionLabels` return typed tuples in declaration
order. Use them to share the declared option set with validation or messages.

<BacklitExample path="fields/enum/option_helpers" view="detail" />

## Clone

Use `configure` to reuse the choice set with different field options. The
source field does not change.

<BacklitExample path="fields/enum/clone" view="detail" />

## All options

You can use option tones, a label, description, display variant, input variant, and
cardinality on the same enum field.

<BacklitExample path="fields/enum/all_options" view="detail" />

## Fetched options

`inputVariant` also accepts `lookupVia(...)` and `optionsVia(...)`. The enum's
static choices still define its display values. The input fetches choices from
the lookup. See [Lookup targets](/reference/targets/lookup).