Overview

Widgets define the data type and interface for entry fields. Static CMS comes with several built-in widgets. Click the widget names in the sidebar to jump to specific widget details. You can also create your own!

Widgets are specified as collection fields in the Static CMS config file. Note that YAML syntax allows lists and objects to be written in block or inline style, and the code samples below include a mix of both.

To see working examples of all of the built-in widgets, try making a ‘Kitchen Sink’ collection item on the CMS demo site. (No login required: click the login button and Static CMS will open.) You can refer to the demo configuration code to see how each field was configured.

Available Widgets

Name	Description
Boolean	The boolean widget translates a toggle switch input to a true or false value
Code	The code widget provides a code editor (powered by Codemirror) with optional syntax awareness
Color	The color widget translates a color picker to a color string
Datetime	The datetime widget translates a datetime picker to a datetime string
File	The file widget allows editors to upload a file or select an existing one from the media library
Hidden	Hidden widgets do not display in the UI
Image	The file widget allows editors to upload a file or select an existing one from the media library
Key Value	The key value widget allows editors to enter an arbitrary number of key/value pairs.
List	The list widget allows you to create a repeatable item in the UI which saves as a list of widget values
Map	The map widget allows you to edit spatial data using an interactive map
Markdown	The markdown widget provides a full fledged text editor allowing users to format text with features such as headings and blockquotes
Number	The number widget uses an HTML number input
Object	The object widget allows you to group multiple widgets together, nested under a single field
Relation	The relation widget allows you to reference items from another collection
Select	The select widget allows you to pick a string value from a dropdown menu
String	The string widget translates a basic text input to a string value
Text	The text widget takes a multiline text field and saves it as a string
UUID	The uuid widget generates a unique id (uuid) and saves it as a string

Common widget options

The following options are available on all fields:

Name	Type	Default	Description
name	string		The name of the field
widget	string	`'string'`	Optional. The type of widget to render for the field
label	string	`name`	Optional. The display name of the field
required	boolean	`true`	Optional. Specify as `false` to make a field optional
hint	string		Optional. Adds helper text directly below a widget. Useful for including instructions. Accepts markdown for bold, italic, strikethrough, and links.
pattern	list of strings		Optional. Adds field validation by specifying a list with a regex pattern and an error message; more extensive validation can be achieved with custom widgets
i18n	boolean \| ‘translate’ \| ‘duplicate’ \| ‘none’		Optional. `translate` – Allows translation of the field`duplicate` – Duplicates the value from the default locale`true` – Accept parent values as default`none` or `false` – Exclude field from translations
condition	FilterRule \| List of FilterRules		Optional. See Field Conditions

name: title
label: Title
widget: string
pattern: ['.{12,}', 'Must have at least 12 characters']

name: 'title',
label: 'Title',
widget: 'string',
pattern: ['.{12,}', 'Must have at least 12 characters'],

Field Conditions

The fields can be shown conditionally based on the values of the other fields.

The condition option can take a single filter rule or a list of filter rules.

Name	Type	Default	Description
field	string		The name of one of the field.
value	string \| list of strings		Optional. The desired value or values to match. Required if no `pattern` provided. Ignored if `pattern` is provided
pattern	regular expression		Optional. A regex pattern to match against the field’s value
matchAll	boolean	`false`	Optional. Ignored if value is not a list of strings `true` – The field’s values must include or match all of the filter rule’s values`false` – The field’s value must include or match only one of the filter rule’s values

Example

The example below conditionally shows fields based on the values of other fields.

YAML
JavaScript

collections:
  - name: 'nested-field-filtered-collection'
    label: 'Nested Field Filtered Collection'
    folder: '_field_condition'
    create: true
    fields:
      - name: type
        label: Type
        widget: select
        options:
          - value: type1
            label: Type 1
          - value: type2
            label: Type 2
      - name: value1
        label: Value 1
        widget: string
        condition:
          field: type
          value: type1
      - name: value2
        label: Value 2
        widget: text
        condition:
          field: type
          value: type2

collections: [
  {
    name: "nested-field-filtered-collection",
    label: "Nested Field Filtered Collection",
    folder: "_field_condition",
    create: true,
    fields: [
      {
        name: "type",
        label: "Type",
        widget: "select",
        options: [
          {
            value: "type1",
            label: "Type 1"
          },
          {
            value: "type2",
            label: "Type 2"
          }
        ]
      },
      {
        name: "value1",
        label: "Value 1",
        widget: "string",
        condition: {
          field: "type",
          value: "type1"
        }
      },
      {
        name: "value2",
        label: "Value 2",
        widget: "text",
        condition: {
          field: "type",
          value: "type2"
        }
      }
    ]
  }
],

Nested Field Example

The example below conditionally shows fields based on the values of other nested fields.

YAML
JavaScript

collections:
  - name: 'nested-field-filtered-collection'
    label: 'Nested Field Filtered Collection'
    folder: '_nested_field_condition'
    create: true
    fields:
      - name: value
        label: Value 1
        widget: string
        condition:
          field: nested.object.field
          value: yes
      - name: nested
        label: Nested
        widget: object
        fields:
          - name: object
            label: Object
            widget: object
            fields:
              - name: field
                label: Field
                widget: select
                options:
                  - yes
                  - no

collections: [
  {
    name: "nested-field-filtered-collection",
    label: "Nested Field Filtered Collection",
    folder: "_nested_field_condition",
    create: true,
    fields: [
      {
        name: "value",
        label: "Value 1",
        widget: "string",
        condition: {
          field: "nested.object.field",
          value: "yes"
        }
      },
      {
        name: "nested",
        label: "Nested",
        widget: "object",
        fields: [
          {
            name: "object",
            label: "Object",
            widget: "object",
            fields: [
              {
                name: "field",
                label: "Field",
                widget: "select",
                options: [
                  "yes",
                  "no"
                ]
              }
            ]
          }
        ]
      }
    ]
  }
],

List Field Example

The example below conditionally shows fields inside a list based on the values of other fields in the same list item. This works with both fields or types.

YAML
JavaScript

collections:
  - name: list-field-filtered-collection
    label: List Field Filtered Collection
    folder: _list_field_condition
    create: true
    fields:
      - name: list
        label: List Field
        widget: list
        fields:
          - name: value
            label: Value 1
            widget: string
            condition:
              field: nested.object.field
              value: yes
          - name: nested
            label: Nested
            widget: object
            fields:
              - name: object
                label: Object
                widget: object
                fields:
                  - name: field
                    label: Field
                    widget: select
                    options:
                      - yes
                      - no

collections: [
  {
    name: "list-field-filtered-collection",
    label: "List Field Filtered Collection",
    folder: "_list_field_condition",
    create: true,
    fields: [
      {
        name: "list",
        label: "List Field",
        widget: "list",
        fields: [
          {
            name: "value",
            label: "Value 1",
            widget: "string",
            condition: {
              field: "nested.object.field",
              value: "yes"
            }
          },
          {
            name: "nested",
            label: "Nested",
            widget: "object",
            fields: [
              {
                name: "object",
                label: "Object",
                widget: "object",
                fields: [
                  {
                    name: "field",
                    label: "Field",
                    widget: "select",
                    options: [
                      "yes",
                      "no"
                    ]
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  }
],

docs