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: An 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 within a field list. 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 — it’s up to you to choose a consistent style. However, it cannot contain spaces or special characters like a dot (.) or an asterisk (*).

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. See the Data Output documentation for more details.

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 description or comment for the field. It’s displayed between the field label and the field input in the UI. Basic Markdown formatting is supported, including bold, italics, links, and inline code.

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, links, and inline code.

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.

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."
]

JavaScript

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 or duplicate
• Default: false

Indicates whether the field supports internationalization (i18n). 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.

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"
    }
  ]
}

JavaScript

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:

Markdown

---
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."
}