Sveltia CMS

Object Field ​

The Object field type allows users to create and manage nested objects within the CMS entry form. It provides a structured way to group related fields together.

User Interface ​

Editor ​

The Object field type has two different UI modes, depending on the configuration. You can have conditional subfields using either the fields option or the types option.

  • With the fields option: A group of subfield editors is shown within a collapsible section. If required is set to false, a checkbox to add or remove the object is displayed.
  • With the types option: A type selector is shown, along with the corresponding subfield editors for the selected type. This configuration is called a variable type object. It’s useful for creating flexible content structures like page builders.

Preview ​

A read-only view of the object’s content, displaying the values of its nested fields in a structured format.

Data Type ​

An object containing nested fields as defined in the configuration.

If the required option is set to false and subfields are not added, the value will be null.

Data Validation ​

  • If the required option is set to true, the object must not be null (i.e., a type must be selected if using variable types).

Options ​

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

Required Options ​

widget ​

  • Type: string
  • Default: string

Must be set to object to use the Object field type.

fields ​

Either fields or types must be provided. You cannot use both options simultaneously.

types ​

  • Type: array of variable type definitions

Either fields or types must be provided. You cannot use both options simultaneously.

Each type definition is an object with the following properties:

  • name (string, required): The unique identifier for the type.
  • label (string, optional): The display label for the type. Defaults to name.
  • widget (string, optional): The field type for this type. It must be object if not omitted. Another field type is reported as a config validation error on the login screen.
  • summary (string, optional): A template for the summary shown when the object of this type is collapsed. Overrides the field-level summary.
  • fields (array of field definitions, optional): The subfields for this type.

Optional Options ​

default ​

  • Type: object
  • Default: {}

The default value for the object field: an object whose keys are the subfield names. For an object with types, it must also include the typeKey property (type by default) to identify the variable type, and its other keys are the names of that type’s subfields.

A property that isn’t a subfield name, a missing type key or a type name that isn’t one of the types is reported as a config validation error on the login screen, because it would otherwise be saved to the entry as-is or leave the object empty.

collapsed ​

  • Type: boolean or auto
  • Default: false

Whether the object field is initially collapsed in the UI. If set to auto, the UI is collapsed if the object has any filled subfields and expanded if all the subfields are empty.

summary ​

  • Type: string
  • Default: ""

A string template used to generate a summary of the object’s content when it is collapsed in the UI. The template can include placeholders for subfield values using the syntax {{fieldName}}. String transformations can be applied in this option.

See the Using Summary and Thumbnail example below for details.

thumbnail ​

  • Type: string
  • Default: ""

The name of an Image or File subfield to be used as the thumbnail of the object when it is collapsed in the UI. The thumbnail is displayed next to the summary. A File subfield holding an image, video or PDF gets a thumbnail; other kinds of files are not shown. If omitted, no thumbnail will be displayed.

A subfield of a nested object can be referenced with dot notation, e.g. mobile.src. Like the summary template tags, the name can be prefixed with fields.. A name that doesn’t point to an Image or File subfield is reported as a config validation error on the login screen. With types, a name shared by the subfields of several types is accepted as long as one of them is an Image or File field.

See the Using Summary and Thumbnail example below for details.

typeKey ​

  • Type: string
  • Default: "type"

The key used to store the selected type name in a variable type object. The default key is type.

You cannot use a key that conflicts with any of the subfield names defined in the object.

TIP

Unlike most of other config options, typeKey is camelCased.

Examples ​

Standard Object ​

The following example defines an Object field named author with two subfields: name (a string) and bio (a text area).

yaml
- name: author
  label: Author
  widget: object
  fields:
    - name: name
      label: Name
      widget: string
    - name: bio
      label: Biography
      widget: text
toml
[[fields]]
name = "author"
label = "Author"
widget = "object"

[[fields.fields]]
name = "name"
label = "Name"
widget = "string"

[[fields.fields]]
name = "bio"
label = "Biography"
widget = "text"
json
{
  "name": "author",
  "label": "Author",
  "widget": "object",
  "fields": [
    {
      "name": "name",
      "label": "Name",
      "widget": "string"
    },
    {
      "name": "bio",
      "label": "Biography",
      "widget": "text"
    }
  ]
}
js
{
  name: "author",
  label: "Author",
  widget: "object",
  fields: [
    {
      name: "name",
      label: "Name",
      widget: "string",
    },
    {
      name: "bio",
      label: "Biography",
      widget: "text",
    },
  ],
},

Output example:

yaml
author:
  name: Jane Doe
  bio: Jane Doe is a writer and editor with over 10 years of experience.
toml
[author]
name = "Jane Doe"
bio = "Jane Doe is a writer and editor with over 10 years of experience."
json
{
  "author": {
    "name": "Jane Doe",
    "bio": "Jane Doe is a writer and editor with over 10 years of experience."
  }
}

Nested Object ​

An object can contain another object as a subfield. The following example defines an Object field named book with a nested Object field named publisher.

yaml
- name: book
  label: Book
  widget: object
  fields:
    - name: title
      label: Title
      widget: string
    - name: publisher
      label: Publisher
      widget: object
      fields:
        - name: name
          label: Name
          widget: string
        - name: address
          label: Address
          widget: text
toml
[[fields]]
name = "book"
label = "Book"
widget = "object"
[[fields.fields]]
name = "title"
label = "Title"
widget = "string"
[[fields.fields]]
name = "publisher"
label = "Publisher"
widget = "object"
[[fields.fields.fields]]
name = "name"
label = "Name"
widget = "string"
[[fields.fields.fields]]
name = "address"
label = "Address"
widget = "text"
json
{
  "name": "book",
  "label": "Book",
  "widget": "object",
  "fields": [
    {
      "name": "title",
      "label": "Title",
      "widget": "string"
    },
    {
      "name": "publisher",
      "label": "Publisher",
      "widget": "object",
      "fields": [
        {
          "name": "name",
          "label": "Name",
          "widget": "string"
        },
        {
          "name": "address",
          "label": "Address",
          "widget": "text"
        }
      ]
    }
  ]
}
js
{
  name: "book",
  label: "Book",
  widget: "object",
  fields: [
    {
      name: "title",
      label: "Title",
      widget: "string",
    },
    {
      name: "publisher",
      label: "Publisher",
      widget: "object",
      fields: [
        {
          name: "name",
          label: "Name",
          widget: "string",
        },
        {
          name: "address",
          label: "Address",
          widget: "text",
        },
      ],
    },
  ],
},

Output example:

yaml
book:
  title: The Great Gatsby
  publisher:
    name: Scribner
    address: '123 Publisher St, New York, NY'
toml
[book]
title = "The Great Gatsby"
[book.publisher]
name = "Scribner"
address = "123 Publisher St, New York, NY"
json
{
  "book": {
    "title": "The Great Gatsby",
    "publisher": {
      "name": "Scribner",
      "address": "123 Publisher St, New York, NY"
    }
  }
}

Using Summary and Thumbnail ​

The following example defines an Object field named hero that, when collapsed, shows the heading subfield value as the summary along with the image held by the image subfield.

yaml
- name: hero
  label: Hero
  widget: object
  summary: "{{heading}}"
  thumbnail: "image"
  fields:
    - name: heading
      label: Heading
      widget: string
    - name: image
      label: Image
      widget: image
toml
[[fields]]
name = "hero"
label = "Hero"
widget = "object"
summary = "{{heading}}"
thumbnail = "image"
[[fields.fields]]
name = "heading"
label = "Heading"
widget = "string"
[[fields.fields]]
name = "image"
label = "Image"
widget = "image"
json
{
  "name": "hero",
  "label": "Hero",
  "widget": "object",
  "summary": "{{heading}}",
  "thumbnail": "image",
  "fields": [
    {
      "name": "heading",
      "label": "Heading",
      "widget": "string"
    },
    {
      "name": "image",
      "label": "Image",
      "widget": "image"
    }
  ]
}
js
{
  name: "hero",
  label: "Hero",
  widget: "object",
  summary: "{{heading}}",
  thumbnail: "image",
  fields: [
    {
      name: "heading",
      label: "Heading",
      widget: "string",
    },
    {
      name: "image",
      label: "Image",
      widget: "image",
    },
  ],
}

Variable Type ​

The following example defines a variable type Object field named contentBlock with three types: textBlock, imageBlock, and placeholderBlock. Note that the placeholderBlock type does not have any subfields but is still a valid type.

yaml
- name: contentBlock
  label: Content Block
  widget: object
  types:
    - name: textBlock
      label: Text Block
      fields:
        - name: text
          label: Text
          widget: text
    - name: imageBlock
      label: Image Block
      fields:
        - name: image
          label: Image
          widget: image
    - name: placeholderBlock
      label: Placeholder Block
toml
[[fields]]
name = "contentBlock"
label = "Content Block"
widget = "object"

[[fields.types]]
name = "textBlock"
label = "Text Block"

[[fields.types.fields]]
name = "text"
label = "Text"
widget = "text"

[[fields.types]]
name = "imageBlock"
label = "Image Block"

[[fields.types.fields]]
name = "image"
label = "Image"
widget = "image"

[[fields.types]]
name = "placeholderBlock"
label = "Placeholder Block"
json
{
  "name": "contentBlock",
  "label": "Content Block",
  "widget": "object",
  "types": [
    {
      "name": "textBlock",
      "label": "Text Block",
      "fields": [
        {
          "name": "text",
          "label": "Text",
          "widget": "text"
        }
      ]
    },
    {
      "name": "imageBlock",
      "label": "Image Block",
      "fields": [
        {
          "name": "image",
          "label": "Image",
          "widget": "image"
        }
      ]
    }
    {
      "name": "placeholderBlock",
      "label": "Placeholder Block"
    }
  ]
}
js
{
  name: "contentBlock",
  label: "Content Block",
  widget: "object",
  types: [
    {
      name: "textBlock",
      label: "Text Block",
      fields: [
        {
          name: "text",
          label: "Text",
          widget: "text",
        },
      ],
    },
    {
      name: "imageBlock",
      label: "Image Block",
      fields: [
        {
          name: "image",
          label: "Image",
          widget: "image",
        },
      ],
    },
    {
      name: "placeholderBlock",
      label: "Placeholder Block",
    },
  ],
},

The output will vary based on the selected type, which is indicated by the type key (customizable via the typeKey option). If no fields are defined for a type, the object will only contain the type key, as shown in the placeholderBlock example below.

Output example for a textBlock type:

yaml
contentBlock:
  type: textBlock
  text: 'This is a sample text block.'
toml
[contentBlock]
type = "textBlock"
text = "This is a sample text block."
json
{
  "contentBlock": {
    "type": "textBlock",
    "text": "This is a sample text block."
  }
}

Output example for an imageBlock type:

yaml
contentBlock:
  type: imageBlock
  image: /images/sample.jpg
toml
[contentBlock]
type = "imageBlock"
image = "/images/sample.jpg"
json
{
  "contentBlock": {
    "type": "imageBlock",
    "image": "/images/sample.jpg"
  }
}

Output example for a placeholderBlock type:

yaml
contentBlock:
  type: placeholderBlock
toml
[contentBlock]
type = "placeholderBlock"
json
{
  "contentBlock": {
    "type": "placeholderBlock"
  }
}

Copyright © 2026 Kohei Yoshino