KeyValue Field

The KeyValue field type allows users to create and manage a dynamic list of key-value pairs, or dictionary entries, within the CMS entry form.

User Interface

Editor

A dynamic list of key-value pairs, where users can add, edit, and remove entries. Each entry consists of a text input for the key and a text input for the value.

You can press Enter to move focus or add a new row while editing.

Preview

A table displaying the current key-value pairs in a structured format for easy review.

Data Type

An object where each key corresponds to a user-defined key and each value corresponds to the associated value.

If the required option is set to false and the field is left empty, the value will be an empty object.

Data Validation

• If the required option is set to true, at least one key-value pair must be present.
• Keys must be unique and non-empty strings. Keys cannot contain dots (.) as they may interfere with nested data structures.
• If min and/or max options are specified, the number of key-value pairs must be within the defined limits.

Options

In addition to the common field options, the KeyValue field supports the following options:

Required Options

widget

• Type: string
• Default: string

Must be set to keyvalue.

Optional Options

default

• Type: object
• Default: {}

The default value for the field when creating a new entry.

key_label

• Type: string
• Default: "Key" or its localized equivalent

The label for the key input field.

value_label

• Type: string
• Default: "Value" or its localized equivalent

The label for the value input field.

min

• Type: integer
• Default: 0

The minimum number of key-value pairs required. This enables validation to ensure that users add at least this many entries.

max

• Type: integer
• Default: Infinity

The maximum number of key-value pairs allowed. This enables validation to prevent users from adding more than this many entries.

root

• Type: boolean
• Default: false

If set to true, the key-value pairs will be stored at the root level of the entry data instead of nested under the field name. This is similar to how the root option for the List field works. The option is ignored if the file or singleton contains multiple fields.

See the Top-Level key-value pairs example below for details.

Examples

Basic Key-Value Field

This example demonstrates a simple KeyValue field configuration:

YAML

- name: settings
  label: Settings
  widget: keyvalue

TOML

[[fields]]
name = "settings"
label = "Settings"
widget = "keyvalue"

JSON

{
  "name": "settings",
  "label": "Settings",
  "widget": "keyvalue"
}

JavaScript

{
  name: 'settings',
  label: 'Settings',
  widget: 'keyvalue',
}

Output example:

YAML

settings:
  theme: dark
  notifications: enabled

TOML

[settings]
theme = "dark"
notifications = "enabled"

JSON

{
  "settings": {
    "theme": "dark",
    "notifications": "enabled"
  }
}

Top-Level Key-Value Pairs

This example demonstrates how to use the root option to store key-value pairs at the root level of the entry data:

YAML

- name: settings
  label: Settings
  widget: keyvalue
  root: true

TOML

[[fields]]
name = "settings"
label = "Settings"
widget = "keyvalue"
root = true

JSON

{
  "name": "settings",
  "label": "Settings",
  "widget": "keyvalue",
  "root": true
}

JavaScript

{
  name: 'settings',
  label: 'Settings',
  widget: 'keyvalue',
  root: true,
}

Output example:

YAML

theme: dark
notifications: enabled

TOML

theme = "dark"
notifications = "enabled"

JSON

{
  "theme": "dark",
  "notifications": "enabled"
}