---
url: /en/docs/fields/object.md
description: Create and manage nested objects in Sveltia CMS within entry forms.
---

# 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](/en/docs/fields#common-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`

* **Type**: `array` of [field definitions](/en/docs/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`](#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`](#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](/en/docs/string-transformations) can be applied in this option.

See the [Using Summary and Thumbnail](#using-summary-and-thumbnail) example below for details.

#### `thumbnail`

* **Type**: `string`
* **Default**: `""`

The name of an [Image](/en/docs/fields/image) or [File](/en/docs/fields/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](#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).

::: code-group

```yaml [YAML]
- name: author
  label: Author
  widget: object
  fields:
    - name: name
      label: Name
      widget: string
    - name: bio
      label: Biography
      widget: text
```

```toml [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 [JSON]
{
  "name": "author",
  "label": "Author",
  "widget": "object",
  "fields": [
    {
      "name": "name",
      "label": "Name",
      "widget": "string"
    },
    {
      "name": "bio",
      "label": "Biography",
      "widget": "text"
    }
  ]
}
```

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

:::

Output example:

::: code-group

```yaml [YAML]
author:
  name: Jane Doe
  bio: Jane Doe is a writer and editor with over 10 years of experience.
```

```toml [TOML]
[author]
name = "Jane Doe"
bio = "Jane Doe is a writer and editor with over 10 years of experience."
```

```json [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`.

::: code-group

```yaml [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 [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 [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 [JavaScript]
{
  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:

::: code-group

```yaml [YAML]
book:
  title: The Great Gatsby
  publisher:
    name: Scribner
    address: '123 Publisher St, New York, NY'
```

```toml [TOML]
[book]
title = "The Great Gatsby"
[book.publisher]
name = "Scribner"
address = "123 Publisher St, New York, NY"
```

```json [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.

::: code-group

```yaml{4-5} [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{5-6} [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{5-6} [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{5-6} [JavaScript]
{
  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.

::: code-group

```yaml [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 [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 [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 [JavaScript]
{
  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:

::: code-group

```yaml [YAML]
contentBlock:
  type: textBlock
  text: 'This is a sample text block.'
```

```toml [TOML]
[contentBlock]
type = "textBlock"
text = "This is a sample text block."
```

```json [JSON]
{
  "contentBlock": {
    "type": "textBlock",
    "text": "This is a sample text block."
  }
}
```

:::

Output example for an `imageBlock` type:

::: code-group

```yaml [YAML]
contentBlock:
  type: imageBlock
  image: /images/sample.jpg
```

```toml [TOML]
[contentBlock]
type = "imageBlock"
image = "/images/sample.jpg"
```

```json [JSON]
{
  "contentBlock": {
    "type": "imageBlock",
    "image": "/images/sample.jpg"
  }
}
```

:::

Output example for a `placeholderBlock` type:

::: code-group

```yaml [YAML]
contentBlock:
  type: placeholderBlock
```

```toml [TOML]
[contentBlock]
type = "placeholderBlock"
```

```json [JSON]
{
  "contentBlock": {
    "type": "placeholderBlock"
  }
}
```

:::