Sveltia CMS

Appearance

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, required): The display label for the type.
  • widget (string, optional): The field type for this type. It must be object if not omitted. Other field types are invalid.
  • fields (array of field definitions, optional): The subfields for this type.

Optional Options ​

default ​

  • Type: object
  • Default: {}

The default value for the object field.

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.

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

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

Released under the MIT License.

Copyright © 2026 Kohei Yoshino