---
url: /en/docs/collections/singletons.md
description: >-
  Use singleton collections in Sveltia CMS to manage pre-defined data files and
  unique resources.
---

# Singletons

The Singleton collection is a special type of file collection that allows you to manage a set of pre-defined data files, each representing a unique resource in your project. Unlike regular file collections, the Singleton collection does not have a collection name or label, and each file is defined directly at the root level of the configuration.

::: tip

Singletons may be referred to as “singles” or “singular resources” in other CMSs.

:::

## Differences from File Collections

The differences between the Singleton collection and a regular [file collection](/en/docs/collections/files) are as follows:

### Configuration

* The Singleton collection does not have the `name` or `label` property at the root level of the configuration.
* Each file in the Singleton collection is defined directly under the `singletons` array at the root level of the configuration, rather than being nested under a `files` property within a named collection.
* Singleton files cannot be nested within folders; each file must be defined at the top level of the `singletons` array.

### User Interface

* On desktop, singleton files appear directly in the sidebar under the “Singletons” group, rather than within a collection that shows a list of files.
  * When clicking on a singleton file in the sidebar, the editor opens directly for that file.
  * However, if there are no other collections, the Singleton collection appears as a regular file collection.
* On mobile, singleton files are accessible via a dedicated “Singletons” section in the content library.

## When to Use Singletons

If your project has multiple similar files, you might consider creating a regular [file collection](/en/docs/collections/files) and include all your relevant files there. A typical example is a `pages` collection that contains multiple page files like `home`, `about`, and `contact`.

However, if your project has only a few pages or configuration files that are not part of a larger collection, using singletons can be more straightforward.

For example, you might have a `home` page and a `settings` file that you want to manage. Instead of creating a `pages` collection with just one file, you can define these files directly in the Singleton collection.

## Creating the Singleton Collection

To create this special file collection, add the new `singletons` option, along with an array of file definitions, to the root level of your CMS configuration.

Here’s an example configuration with two singleton files:

::: code-group

```yaml [YAML]
singletons:
  - name: home
    label: Home Page
    file: content/home.yaml
    fields:
      - { label: Title, name: title }
      - { label: Body, name: body, widget: richtext }
  - name: settings
    label: Site Settings
    file: content/settings.yaml
    fields:
      - { label: Site Title, name: site_title }
      - { label: Description, name: description, widget: text }
```

```toml [TOML]
[[singletons]]
name = "home"
label = "Home Page"
file = "content/home.yaml"

[[singletons.fields]]
label = "Title"
name = "title"

[[singletons.fields]]
label = "Body"
name = "body"
widget = "richtext"

[[singletons]]
name = "settings"
label = "Site Settings"
file = "content/settings.yaml"

[[singletons.fields]]
label = "Site Title"
name = "site_title"

[[singletons.fields]]
label = "Description"
name = "description"
widget = "text"
```

```json [JSON]
{
  "singletons": [
    {
      "name": "home",
      "label": "Home Page",
      "file": "content/home.yaml",
      "fields": [
        { "label": "Title", "name": "title" },
        { "label": "Body", "name": "body", "widget": "richtext" }
      ]
    },
    {
      "name": "settings",
      "label": "Site Settings",
      "file": "content/settings.yaml",
      "fields": [
        { "label": "Site Title", "name": "site_title" },
        { "label": "Description", "name": "description", "widget": "text" }
      ]
    }
  ]
}
```

```js [JavaScript]
{
  singletons: [
    {
      name: "home",
      label: "Home Page",
      file: "content/home.yaml",
      fields: [
        { label: "Title", name: "title" },
        { label: "Body", name: "body", widget: "richtext" },
      ],
    },
    {
      name: "settings",
      label: "Site Settings",
      file: "content/settings.yaml",
      fields: [
        { label: "Site Title", name: "site_title" },
        { label: "Description", name: "description", widget: "text" },
      ],
    },
  ],
}
```

:::

File options are the same as those for [file collections](/en/docs/collections/files).

## Converting from File Collections

It’s easy to convert an existing file collection into the Singleton collection. This is a conventional file collection:

::: code-group

```yaml [YAML]{1-4}
collections:
  - name: data
    label: Data
    files:
      - name: home
        label: Home Page
        file: content/home.yaml
        fields: ...
      - name: settings
        label: Site Settings
        file: content/settings.yaml
        fields: ...
```

```toml [TOML]{1-3}
[[collections]]
name = "data"
label = "Data"

[[collections.files]]
name = "home"
label = "Home Page"
file = "content/home.yaml"

[[collections.files]]
name = "settings"
label = "Site Settings"
file = "content/settings.yaml"
```

```json [JSON]{2-6}
{
  "collections": [
    {
      "name": "data",
      "label": "Data",
      "files": [
        {
          "name": "home",
          "label": "Home Page",
          "file": "content/home.yaml"
        },
        {
          "name": "settings",
          "label": "Site Settings",
          "file": "content/settings.yaml"
        }
      ]
    }
  ]
}
```

```js [JavaScript]{2-6}
{
  collections: [
    {
      name: "data",
      label: "Data",
      files: [
        {
          name: "home",
          label: "Home Page",
          file: "content/home.yaml",
        },
        {
          name: "settings",
          label: "Site Settings",
          file: "content/settings.yaml",
        },
      ],
    },
  ],
}
```

:::

It can be converted to the Singleton collection like this:

::: code-group

```yaml [YAML]{1}
singletons:
  - name: home
    label: Home Page
    file: content/home.yaml
    fields: ...
  - name: settings
    label: Site Settings
    file: content/settings.yaml
    fields: ...
```

```toml [TOML]
[[singletons]]
name = "home"
label = "Home Page"
file = "content/home.yaml"

[[singletons]]
name = "settings"
label = "Site Settings"
file = "content/settings.yaml"
```

```json [JSON]{2}
{
  "singletons": [
    {
      "name": "home",
      "label": "Home Page",
      "file": "content/home.yaml"
    },
    {
      "name": "settings",
      "label": "Site Settings",
      "file": "content/settings.yaml"
    }
  ]
}
```

```js [JavaScript]{2}
{
  singletons: [
    {
      name: "home",
      label: "Home Page",
      file: "content/home.yaml",
    },
    {
      name: "settings",
      label: "Site Settings",
      file: "content/settings.yaml",
    },
  ],
}
```

:::

## Adding Icons and Dividers

You can add icons to singleton items using the `icon` option, and you can add dividers between items using the `divider` option. Here’s an example:

::: code-group

```yaml [YAML]{5,7,11}
singletons:
  - name: home
    label: Home Page
    file: content/home.yaml
    icon: home
    fields: ...
  - divider: true
  - name: settings
    label: Site Settings
    file: content/settings.yaml
    icon: settings
    fields: ...
```

```toml [TOML]{5,8,14}
[[singletons]]
name = "home"
label = "Home Page"
file = "content/home.yaml"
icon = "home"

[[singletons]]
divider = true

[[singletons]]
name = "settings"
label = "Site Settings"
file = "content/settings.yaml"
icon = "settings"
```

```json [JSON]{7,10,16}
{
  "singletons": [
    {
      "name": "home",
      "label": "Home Page",
      "file": "content/home.yaml",
      "icon": "home"
    },
    {
      "divider": true
    },
    {
      "name": "settings",
      "label": "Site Settings",
      "file": "content/settings.yaml",
      "icon": "settings"
    }
  ]
}
```

```js [JavaScript]{7,10,16}
{
  singletons: [
    {
      name: "home",
      label: "Home Page",
      file: "content/home.yaml",
      icon: "home",
    },
    {
      divider: true,
    },
    {
      name: "settings",
      label: "Site Settings",
      file: "content/settings.yaml",
      icon: "settings",
    },
  ],
}
```

:::

## Referencing Singleton Files

Singletons belong to a collection named `_singletons` (note the underscore prefix). Use this name wherever a collection name is expected, along with the singleton’s `name` as the file name:

* In a [Relation](/en/docs/fields/relation) field, set `collection` to `_singletons` and `file` to the singleton’s name.
* In a [custom preview template](/en/docs/api/preview-templates), call `getCollection('_singletons', 'settings')` to get the `settings` singleton, or `getCollection('_singletons')` to get all the singletons. `getCollection('settings')` doesn’t work, because `settings` is a file name, not a collection name.
* In a custom preview template or an [event hook](/en/docs/api/events), the `collection` property of a singleton’s entry is `_singletons`.

`registerPreviewTemplate()` is different: like with a file collection, it takes the file name, which is the singleton’s own name, e.g. `registerPreviewTemplate('settings', SettingsPreview)`.