Sveltia CMS

Fields ​

Each collection requires a fields property that defines the structure of the content within the collection. Fields specify the type of data to be collected, such as text, images, dates, or custom types.

Field Types ​

A field type determines how a field is rendered and interacted with in the CMS. Each field type has its own set of options, behaviors, validations, and data formats.

Note for Netlify/Decap CMS users

In Sveltia CMS, what was previously referred to as a widget in Netlify/Decap CMS is now called a field type. This change was made to better align with common content management terminology, as originally proposed by Netlify CMS maintainers themselves.

The functionality and configuration options remain the same. The widget property is still used in the configuration for backward compatibility.

Built-in field types ​

Sveltia CMS includes the following field types out of the box:

  • Boolean: A toggle switch for true/false values.
  • Code: A code editor for various programming languages.
  • Color: A color picker.
  • Compute: A read-only field that computes its value based on other fields.
  • DateTime: A date and time picker.
  • File: A file uploader and selector.
  • Hidden: A hidden field that is not displayed in the UI.
  • Image: A variant of File with image-specific features.
  • KeyValue: A field for storing key-value pairs.
  • List: A list of items, which can be of any field type.
  • Map: A geo-location picker.
  • Markdown: An alias of RichText.
  • Number: A numeric input field.
  • Object: A field for storing nested objects.
  • Relation: A field for creating relationships between entries in different collections.
  • RichText: A rich text editor with Markdown support.
  • Select: A dropdown or multi-select field.
  • String: A single-line text input.
  • Text: A multi-line text input.
  • UUID: A field that generates a unique identifier.

Breaking change from Netlify CMS

The deprecated Date widget is not supported in Sveltia CMS (and Decap CMS). Use the DateTime widget instead.

Custom field types ​

Developers can create custom field types to extend the functionality of Sveltia CMS.

Designing Fields ​

When designing fields for a collection, consider the following best practices:

  • Use appropriate field types for the data being collected to ensure a good user experience.
  • Provide clear labels and hints to guide users in entering data correctly.
  • Utilize default values where applicable to streamline data entry.
  • Organize fields logically, especially when using nested objects or lists.
  • Leverage the relation field to create connections between different collections, enhancing data integrity and usability.
  • Consider the use of i18n for fields that require localization.
  • Take advantage of field validation to enforce data integrity.
  • Plan for scalability by anticipating future data requirements and structuring fields accordingly.
  • Regularly review and update field configurations to adapt to changing content needs.
  • Test field configurations thoroughly to ensure they meet user requirements and function as expected.

See also the Content Modeling Guide for more in-depth advice on designing content structures.

Common Options ​

In addition to field-specific options, all field types support the following common options.

An exception is the Hidden field type that only supports name, widget, default and i18n options since it has no UI.

Required Options ​

name ​

  • Type: string

The unique identifier for the field among its sibling fields. This option is required for all field types, including the Hidden field type. It’s used as the key in the output data and to reference the field in various contexts, such as in Compute and Relation fields as well as an entry collection’s identifier_field, summary, sortable_fields, and so on.

The naming convention for field names is typically snake_case or camelCase — the choice is yours, but keep the style consistent. However, it cannot contain spaces, periods (.), asterisks (*), colons (:) or angle brackets (<, >).

There are two special field names to be aware of:

  • A field named title is treated as the default identifier_field for an entry collection, meaning it will be used as the entry title and slug unless another field is explicitly set as the identifier_field.
  • A field named body is treated as the main content of the entry, and its value will be placed below the front matter if the collection uses a front matter format like YAML, TOML, or JSON. This behavior can be configured using the body_field option for collections and collection files.

Optional Options ​

widget ​

  • Type: string
  • Default: string

A field type. It’s one of the lowercase names of the built-in field types or a registered custom field type name. If not specified, it defaults to string, which is a single-line text input.

label ​

  • Type: string
  • Default: value of the name option

The human-readable label for the field. It’s displayed in the UI as the field’s title.

comment ​

  • Type: string
  • Default: ""

A comment to be added before the field in the output file. It’s only supported for the yaml format and front matter in YAML. Other formats, such as JSON and TOML, ignore this option. The comment is not displayed in the UI; use the hint option to show a description to users. A line break can be given as \n.

For example, with the following field definition:

yaml
- name: title
  label: Title
  comment: The title of the post, used in the page header

The output file will look like this:

yaml
# The title of the post, used in the page header
title: My First Post

Comments on subfields of an Object field are also added before the corresponding keys, while comments on subfields of a List field or a variable-type Object field are ignored.

hint ​

  • Type: string
  • Default: ""

A short description or hint for the field value, which provides additional context to users. It’s displayed below the field input in the UI. Basic Markdown formatting is supported, including bold, italics, strikethrough, links, and inline code. A line break can be given as a literal backslash followed by n, e.g. \n in a plain or single-quoted YAML string; in JSON or a double-quoted YAML/TOML string, escape the backslash (\\n). A real newline is rendered as a space. The hint is not displayed while the field is read-only.

required ​

  • Type: boolean or array of locale codes
  • Default: true

A boolean indicating whether data input is required for the field. Unless explicitly set to false, fields are required by default, meaning users must provide a value when creating or editing an entry.

If i18n is enabled, the option accepts an array of locale codes to specify which locales require input. For example, required: [en, fr] means that input is required for English and French locales only.

With Editorial Workflow enabled, an entry in draft can be saved with its required fields left empty, so unfinished work isn’t held up. They’re enforced again once the entry moves on from the drafting stage. See Required Fields.

If the omit_empty_optional_fields output option is enabled, this option affects data output as well. The default value is true, meaning optional fields left empty will be omitted from the output. If set to false, optional fields left empty will be included in the output with a value of null, empty string, or empty array/object, depending on the field type.

pattern ​

  • Type: array of string (or RegExp in JavaScript API)

An array containing a regular expression pattern and an error message to validate the field’s value. The regular expression can be provided in one of the following formats:

  • A string representing the regex pattern without delimiters, e.g., '^[A-Za-z0-9]+$'.
  • A string representing the regex pattern with delimiters and flags, e.g., '/^[a-z0-9]+$/i'. The delimiters must be slashes /.
  • A RegExp object when using the JavaScript API.

For example, to restrict a string field to only alphanumeric characters, you can use the following configuration:

yaml
pattern:
  - '^[A-Za-z0-9]+$'
  - 'Only alphanumeric characters are allowed.'
toml
pattern = [ "^[A-Za-z0-9]+$", "Only alphanumeric characters are allowed." ]
json
"pattern": [
  "^[A-Za-z0-9]+$",
  "Only alphanumeric characters are allowed."
]
js
pattern: [/^[A-Za-z0-9]+$/, 'Only alphanumeric characters are allowed.'];

readonly ​

  • Type: boolean
  • Default: false (except for UUID fields, which default to true)

A boolean indicating whether the field is read-only. It’s useful for fields with a default value that should not be modified by users.

preview ​

  • Type: boolean
  • Default: true

Whether to show a preview of the field’s value in the entry’s preview pane. This is useful for fields with large content, such as rich text or code fields, where a preview may not be necessary.

i18n ​

  • Type: boolean, translate, duplicate or none
  • Default: false, or duplicate for a subfield of a field using duplicate

Indicates whether the field supports internationalization (i18n). true (or translate) enables the field in all locales, while false (or none) enables it in the default locale only. duplicate makes the field read-only in non-default locales and copies the default locale’s value to them. A subfield without its own i18n option follows its parent’s duplicate strategy, while under a parent with true, such a subfield is hidden in non-default locales. See the i18n documentation for more details.

Field Validation ​

All visible fields support various validation options to ensure data integrity. Common validation options include:

  • By default, fields are required to be filled out unless the required option is explicitly set to false. If i18n is enabled for a field, all localized versions of the field are required unless specified otherwise.
  • String-type and some other simple array-type fields support the pattern option, which allows you to define a regular expression that the field’s value must match. This is useful for enforcing specific formats.
  • Some fields support minimum and maximum values/items/lengths or value types, depending on the field type. For example:
    • The String field supports minlength and maxlength options as well as the type option that can enforce formats like email or url.
    • The Number field supports min, max and value_type options.
    • Other multi-value fields like List and KeyValue support min and max options.
  • Validation options other than required describe a value, so they only apply to a field that has one. An optional field left empty is valid even when a pattern, minlength, min or similar option is set on it — those rules take effect as soon as something is entered.

If more complicated validation logic is needed, consider creating a custom field type that implements the desired validation behavior.

Examples ​

Blog Post Fields ​

Here is an example configuration for fields in a blog post collection:

yaml
fields:
  - name: title
    label: Title
    widget: string
    hint: The title of the blog post
    default: Untitled Post
  - name: published
    label: Published
    widget: boolean
    required: false
    default: false
  - name: date
    label: Publication Date
    widget: datetime
    default: '{{now}}'
  - name: body
    label: Body
    widget: richtext
toml
[[fields]]
name = "title"
label = "Title"
widget = "string"
hint = "The title of the blog post"
default = "Untitled Post"

[[fields]]
name = "published"
label = "Published"
widget = "boolean"
required = false
default = false

[[fields]]
name = "date"
label = "Publication Date"
widget = "datetime"
default = "{{now}}"

[[fields]]
name = "body"
label = "Body"
widget = "richtext"
json
{
  "fields": [
    {
      "name": "title",
      "label": "Title",
      "widget": "string",
      "hint": "The title of the blog post",
      "default": "Untitled Post"
    },
    {
      "name": "published",
      "label": "Published",
      "widget": "boolean",
      "required": false,
      "default": false
    },
    {
      "name": "date",
      "label": "Publication Date",
      "widget": "datetime",
      "default": "{{now}}"
    },
    {
      "name": "body",
      "label": "Body",
      "widget": "richtext"
    }
  ]
}
js
fields: [
  {
    name: 'title',
    label: 'Title',
    widget: 'string',
    hint: 'The title of the blog post',
    default: 'Untitled Post',
  },
  {
    name: 'published',
    label: 'Published',
    widget: 'boolean',
    required: false,
    default: false,
  },
  {
    name: 'date',
    label: 'Publication Date',
    widget: 'datetime',
    default: '{{now}}',
  },
  {
    name: 'body',
    label: 'Body',
    widget: 'richtext',
  },
];

Output data for a blog post using the above configuration might look like this:

md
---
title: My First Blog Post
published: true
date: 2024-06-15T10:00:00Z
---

# Welcome to my blog

This is the content of my first blog post.
yaml
title: My First Blog Post
published: true
date: 2024-06-15T10:00:00Z
body: |
  # Welcome to my blog

  This is the content of my first blog post.
toml
title = "My First Blog Post"
published = true
date = 2024-06-15T10:00:00Z
body = '''# Welcome to my blog

This is the content of my first blog post.
'''
json
{
  "title": "My First Blog Post",
  "published": true,
  "date": "2024-06-15T10:00:00Z",
  "body": "# Welcome to my blog\n\nThis is the content of my first blog post."
}

Copyright © 2026 Kohei Yoshino