Sveltia CMS

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 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 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:

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
[[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
{
  "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
{
  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.

Converting from File Collections ​

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

yaml
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
[[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
{
  "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
{
  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:

yaml
singletons:
  - name: home
    label: Home Page
    file: content/home.yaml
    fields: ...
  - name: settings
    label: Site Settings
    file: content/settings.yaml
    fields: ...
toml
[[singletons]]
name = "home"
label = "Home Page"
file = "content/home.yaml"

[[singletons]]
name = "settings"
label = "Site Settings"
file = "content/settings.yaml"
json
{
  "singletons": [
    {
      "name": "home",
      "label": "Home Page",
      "file": "content/home.yaml"
    },
    {
      "name": "settings",
      "label": "Site Settings",
      "file": "content/settings.yaml"
    }
  ]
}
js
{
  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:

yaml
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
[[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
{
  "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
{
  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 field, set collection to _singletons and file to the singleton’s name.
  • In a custom preview template, 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, 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).

Copyright © 2026 Kohei Yoshino