--- url: /en/docs/fields.md description: >- Configure fields in Sveltia CMS with built-in types, validation rules, common options, and design best practices. --- # 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. ::: tip 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](https://github.com/decaporg/decap-cms/issues/3719) 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](/en/docs/fields/boolean): A toggle switch for true/false values. * [Code](/en/docs/fields/code): A code editor for various programming languages. * [Color](/en/docs/fields/color): A color picker. * [Compute](/en/docs/fields/compute): A read-only field that computes its value based on other fields. * [DateTime](/en/docs/fields/datetime): A date and time picker. * [File](/en/docs/fields/file): A file uploader and selector. * [Hidden](/en/docs/fields/hidden): A hidden field that is not displayed in the UI. * [Image](/en/docs/fields/image): A variant of [File](/en/docs/fields/file) with image-specific features. * [KeyValue](/en/docs/fields/keyvalue): A field for storing key-value pairs. * [List](/en/docs/fields/list): A list of items, which can be of any field type. * [Map](/en/docs/fields/map): A geo-location picker. * [Markdown](/en/docs/fields/markdown): An alias of [RichText](/en/docs/fields/richtext). * [Number](/en/docs/fields/number): A numeric input field. * [Object](/en/docs/fields/object): A field for storing nested objects. * [Relation](/en/docs/fields/relation): A field for creating relationships between entries in different collections. * [RichText](/en/docs/fields/richtext): A rich text editor with Markdown support. * [Select](/en/docs/fields/select): A dropdown or multi-select field. * [String](/en/docs/fields/string): A single-line text input. * [Text](/en/docs/fields/text): A multi-line text input. * [UUID](/en/docs/fields/uuid): A field that generates a unique identifier. ::: warning 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](/en/docs/api/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](/en/docs/fields/relation) to create connections between different collections, enhancing data integrity and usability. * Consider the use of [i18n](/en/docs/i18n) for fields that require localization. * Take advantage of [field validation](#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](/en/docs/content-modeling) 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](/en/docs/fields/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](/en/docs/fields/compute) and [Relation](/en/docs/fields/relation) fields as well as an [entry collection](/en/docs/collections/entries)’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](/en/docs/collections/entries), 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](/en/docs/collections/entries/formats#body-field-for-front-matter-formats) 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](#built-in-field-types) or a registered [custom field type](/en/docs/api/field-types) 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`](#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](/en/docs/fields/object) field are also added before the corresponding keys, while comments on subfields of a [List](/en/docs/fields/list) field or a [variable-type](/en/docs/fields/object#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](#readonly). #### `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](/en/docs/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](/en/docs/workflows/editorial) 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](/en/docs/workflows/editorial#required-fields). If the `omit_empty_optional_fields` [output option](/en/docs/data-output#controlling-data-output) 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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Regular_expressions) 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](/en/docs/api/initialization). For example, to restrict a string field to only alphanumeric characters, you can use the following configuration: ::: code-group ```yaml [YAML] pattern: - '^[A-Za-z0-9]+$' - 'Only alphanumeric characters are allowed.' ``` ```toml [TOML] pattern = [ "^[A-Za-z0-9]+$", "Only alphanumeric characters are allowed." ] ``` ```json [JSON] "pattern": [ "^[A-Za-z0-9]+$", "Only alphanumeric characters are allowed." ] ``` ```js [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`, `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](/en/docs/i18n/options#field-level-configuration) 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](/en/docs/i18n/options#field-level-configuration). * 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](/en/docs/fields/string) field supports `minlength` and `maxlength` options as well as the `type` option that can enforce formats like `email` or `url`. * The [Number](/en/docs/fields/number) field supports `min`, `max` and `value_type` options. * Other multi-value fields like [List](/en/docs/fields/list) and [KeyValue](/en/docs/fields/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](/en/docs/api/field-types) that implements the desired validation behavior. ## Examples ### Blog Post Fields Here is an example configuration for fields in a blog post collection: ::: code-group ```yaml [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 [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 [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 [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: ::: code-group ```md [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 [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 [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 [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." } ``` :::