Skip to main content
View as Markdown

Selection Fields

Four field types let records choose from predefined options. All share the base field properties.

Type Stores
checkbox A boolean true/false value.
single-select One option chosen from a predefined list.
multi-select Multiple options chosen from a predefined list.
status One option, named as a workflow state.

Option grammar

single-select, multi-select and status share one grammar for options. Every option is either a bare string, or an object — and the two forms mix freely in the same list.

Form Use it when
Draft The stored value is also the display label, and needs no color.
{ value, label?, color? } The option needs a display label, a translation key, a color, or any combination.
Key Description
value Required. The value stored in the database and enforced by the column constraint. Values must be unique across the option list.
label Optional display text. May be a $t: translation key. Defaults to value.
color Optional hex code #RRGGBB painted as the option's chip fill.
app.yaml
options:
  - Draft # bare string
  - { value: review, label: In review }
  - { value: published, label: 'statusPublished', color: '#10B981' }

Changing an option's label or color never rewrites stored data — only value is persisted.

How color renders

A declared color is the fill of the option's chip, never its text color. Sovrium derives the two companions the author did not declare: a foreground meeting WCAG AA contrast (4.5:1) against that fill, and a border in the same hue so a pale chip stays delimited against a pale surface. The declared hex renders exactly as written — it is never clamped or rejected for being low-contrast — and because the pair is derived, the chip reads identically in light and dark mode.

An option that declares no color renders in the default neutral chrome, unchanged. Color is opt-in per option, so a list may paint some options and leave others plain.

checkbox

Boolean field, typically rendered as a checkbox. It takes no options.

Property Description
default Default boolean value (true / false).
app.yaml
- { id: 1, name: is_active, type: checkbox, required: true, default: false }

single-select

A single choice from a declared option list.

Property Description
options The available choices, in the option grammar. At least one required.
default Default selected option (a string matching one of the option values).
conditions Optional behavioral conditions: [{ when: <option>, then: { …property changes } }] — apply property changes (e.g. readOnly) when a specific option is selected.
app.yaml
- id: 2
  name: category
  type: single-select
  options:
    - { value: Electronics, color: '#3B82F6' }
    - { value: Clothing, color: '#8B5CF6' }
    - Food
  default: Electronics

multi-select

Several choices from a declared option list. Each chosen option paints its own chip, so one cell may show several colors.

Property Description
options The available choices, in the option grammar. At least one required.
maxSelections Maximum number of choices (integer ≥ 1; cannot exceed options.length).
default Default selections (an array of strings).
app.yaml
- id: 3
  name: tags
  type: multi-select
  options:
    - { value: Urgent, color: '#EF4444' }
    - { value: Important, color: '#F59E0B' }
    - Review
  maxSelections: 3

status

One option, named as a workflow state — the field type to reach for when the value drives Kanban columns or pipeline stages.

Property Description
options The available states, in the option grammar. At least one required.
default Default status value (a string matching one of the option values).
app.yaml
- id: 4
  name: status
  type: status
  options:
    - { value: todo, label: To do, color: '#94A3B8' }
    - { value: in_progress, label: In progress, color: '#3B82F6' }
    - { value: done, label: Done, color: '#10B981' }
  default: todo

Last updated August 11, 2026

Edit this pageReport an issue

This documentation was written with AI, so errors or outdated content are possible. Sovrium is in beta. Contributions and corrections are welcome.

Built with Sovrium