---
title: "Site settings definitions"
manual: "TYPO3 Explained"
version: "13.4"
permalink: "https://docs.typo3.org/permalink/t3coreapi:site-settings-definition@13.4"
source: "ApiOverview/SiteHandling/SiteSettingDefinitions.rst"
rendered: "2026-09-23T17:02:48+00:00"
---

# Site settings definitions {#site-settings-definition}

<!-- TODO: no Markdown rendering for "versionadded" -->

Site-scoped setting definitions where introduced. They will most likely be
the place to configure site-wide configuration, which was previously only
possible to modify via modifying TypoScript constants, for example in the
Constant Editor.

Site settings definitions allow to define settings with a type and a guaranteed
default value. They can be defined in [Site sets](https://docs.typo3.org/permalink/t3coreapi:site-sets@13.4), in a file called
[`settings.definitions.yaml`](../../ExtensionArchitecture/FileStructure/Configuration/Sets/Index.md#file-set-settings-definitions-yaml).

It is recommended to use site-sets and their UI configuration in favor of
TypoScript Constants.

All available settings are displayed in the [Site settings editor](https://docs.typo3.org/permalink/t3coreapi:site-settings-editor@13.4).

The site settings provided by an extension can be automatically documented in
the extensions manual, see
[site settings documentation](https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ReStructuredText/Code/SiteSettings.html#reference-site-settings).

**Table of contents**

-   [Site setting definition example](https://docs.typo3.org/permalink/t3coreapi:site-setting-definition-example@13.4)
-   [Site setting definition properties](https://docs.typo3.org/permalink/t3coreapi:site-setting-definition-properties@13.4)
-   [Definition types](https://docs.typo3.org/permalink/t3coreapi:definition-types-1@13.4)
-   [Translating labels and descriptions for settings](https://docs.typo3.org/permalink/t3coreapi:translating-labels-and-descriptions-for-settings@13.4)

## Site setting definition example {#site-settings-definition-example}

**EXT:blog_example/Configuration/Sets/BlogExample/settings.definitions.yaml (Excerpt)**

```yaml
categories:
  BlogExample:
    label: 'Blog Example' # (1)
  BlogExample.templates:
    label: 'Templates' # (2)
    parent: BlogExample
  BlogExample.pages:
    label: 'Pages'
    parent: BlogExample

settings:
  blogExample.templateRootPath:  # (5)
    label: 'Templates' # (3)
    category: BlogExample.templates # (2)
    description: 'Path to template root'  # (4)
    type: string  # (6)
    default: 'EXT:blog_example/Resources/Private/Templates/'  # (7) + (8)
  blogExample.partialRootPath:
    label: 'Partials'
    category: BlogExample.templates
    description: 'Path to partial root'
    type: string
    default: 'EXT:blog_example/Resources/Private/Partials/'

```

See the complete example at
[settings.definitions.yaml (GitHub)](https://github.com/TYPO3-Documentation/blog_example/blob/main/Configuration/Sets/BlogExample/settings.definitions.yaml).

![Screenshot demonstration the position of the categories, labels etc](../../Images/ManualScreenshots/SiteHandling/SiteSettingsDefinition.png)

## Site setting definition properties {#site-settings-definition-properties}

-   **categories**

    -   *Type:* array

    -   **label**

        -   *Type:* string

    -   **parent**

        -   *Type:* [categories](https://docs.typo3.org/permalink/t3coreapi:confval-site-settings-definition-categories@13.4) key

-   **settings**

    -   *Type:* array

    -   **label**

        -   *Type:* string

    -   **description**

        -   *Type:* string
        -   *Example:* 'Configure `baz` to be used in `bar`.'

        While Markdown syntax can be used in YAML to provide rich text formatting, there are
        a few gotchas. Because YAML is sensitive to special characters and indentation, you
        might need to wrap your Markdown text in single quotes (') to prevent it from breaking
        the YAML syntax.

    -   **category**

        -   *Type:* [categories](https://docs.typo3.org/permalink/t3coreapi:confval-site-settings-definition-categories@13.4) key

    -   **type**

        -   *Type:* a [definition type](https://docs.typo3.org/permalink/t3coreapi:definition-types@13.4)
        -   *Required:* true

    -   **default**

        -   *Type:* mixed
        -   *Required:* true

        The default value must have the same type like defined in
        [type](https://docs.typo3.org/permalink/t3coreapi:confval-site-settings-definition-settings-type@13.4).

    -   **readonly**

        -   *Type:* bool

        If a site setting is marked as readonly, it can be overridden only
        by editing  the [`config/sites/my-site/settings.yaml`](../../Administration/DirectoryStructure/SiteFolder.md#file-site-config-sites-my-site-settings-yaml) directly,
        but not from within the editor.

    -   **enum**

        -   *Type:* array
        -   *types:* [string](https://docs.typo3.org/permalink/t3coreapi:confval-site-setting-type-string@13.4)

        Site settings can provide possible options via the `enum` specifier,
        that will be selectable in the editor GUI.

        **EXT:my_extension/Configuration/Sets/MySet/settings.definitions.yaml**

        ```yaml
        settings:
          my.enumSetting:
            label: 'My setting with options'
            type: string
            enum:
              valueA: 'Label of value A'
              valueB: 'Label of value B'

        ```

> [!NOTE]
> The `settings.definitions.yaml` does not allow any kind of imports. All
> settings must be defined in a single file.

## Definition types {#definition-types}

-   **int**

    -   *Type:* string
    -   *Path:* settings.\[my_val\].type = int

    ![Screenshot of a site setting field of type int](../../Images/ManualScreenshots/SiteHandling/SiteSettingsTypeInt.png)

    Checks whether the value is already an integer or can be interpreted as an
    integer. If yes, the string is converted into an integer.

    **EXT:my_extension/Configuration/Sets/MySet/settings.definitions.yaml**

    ```yaml
    settings:
      example.types.int:
        type: int
        default: 42
        category: Example.types
        label: 'Type int'
        description: 'Checks whether the value is already an integer or can be
        interpreted as an integer. If yes, the string is converted into an integer.'

    ```

-   **number**

    -   *Type:* string
    -   *Path:* settings.\[my_val\].type = number

    Checks whether the value is already an integer or float or whether the
    string can be interpreted as an integer or float. If yes, the string is
    converted to an integer or float.

    **EXT:my_extension/Configuration/Sets/MySet/settings.definitions.yaml**

    ```yaml
    settings:
      example.types.number:
        type: number
        default: 3.16
        category: Example.types
        label: 'Type number'
        description: 'Checks whether the value is already an integer or float or
          whether the string can be interpreted as an integer or float. If yes,
          the string is converted to an integer or float.'

    ```

-   **bool**

    -   *Type:* string
    -   *Path:* settings.\[my_val\].type = bool

    ![Screenshot of a site setting field of type enum](../../Images/ManualScreenshots/SiteHandling/SiteSettingsTypeBool.png)

    If the value is already a boolean, it is returned directly 1 to 1.

    If the value is an integer, then `false` is returned for 0 and `true` for 1.

    If the value is a string, the corresponding Boolean value is returned for
    `true`, `false`, `yes`, `no`, `on`, `off`, `0` and `1`.

    **EXT:my_extension/Configuration/Sets/MySet/settings.definitions.yaml**

    ```yaml
    settings:
      example.types.bool:
        type: bool
        default: true
        category: Example.types
        label: 'Type bool'
        description: 'Casts the value to a boolean.'
      example.types.bool-false:
        type: bool
        default: false
        category: Example.types
        label: 'Type bool'
        description: 'Casts the value to a boolean.'

    ```

-   **string**

    -   *Type:* string
    -   *Path:* settings.\[my_val\].type = string

    ![Screenshot of a site setting field of type string](../../Images/ManualScreenshots/SiteHandling/SiteSettingsTypeString.png)

    Converts almost all data types into a string. If an object has been
    specified, it must be `stringable`, otherwise no conversion takes place.
    Boolean values are converted to `true` and `false`.

    **EXT:my_extension/Configuration/Sets/MySet/settings.definitions.yaml**

    ```yaml
    settings:
      example.types.string:
        type: string
        default: 'EXT:example/Resources/Private/Templates/'
        category: Example.types
        label: 'Type string'
        description: 'Converts almost all data types into a string. If an object
        has been specified, it must be stringable, otherwise no conversion
        takes place.
        Boolean values are converted to "true" and "false".'

    ```

-   **text**

    -   *Type:* string
    -   *Path:* settings.\[my_val\].type = text

    Exactly the same as the `string` type. Use it as an alias if someone doesn't
    know what to do with `string`.

    **EXT:my_extension/Configuration/Sets/MySet/settings.definitions.yaml**

    ```yaml
    settings:
      example.types.text:
        type: text
        default: 'EXT:example/Resources/Private/Templates/'
        category: Example.types
        label: 'Type text'
        description: 'Exactly the same as the `string` type. Use it as an alias if
        someone doesn''t know what to do with `string`.'

    ```

-   **enum**

    -   *Type:* string
    -   *Path:* settings.\[my_val\].type = enum

    ![Screenshot of a site setting field of type enum](../../Images/ManualScreenshots/SiteHandling/SiteSettingsTypeEnum.png)

    Site settings can provide possible options via the `enum` specifier, that will
    be selectable in the editor GUI.

    ```yaml
    settings:
      example.types.string-enum:
        type: string
        default: 'summer'
        category: Example.types
        label: 'Type string with enum'
        enum:
          spring: 'Spring time'
          summer: 'Seasons in the sun'
          fall: 'Wine harvest'
          winter: 'Cold'
        description: 'Site settings can provide possible options via the `enum`
        specifier, that will be selectable in the editor GUI.'

    ```

-   **stringlist**

    -   *Type:* string
    -   *Path:* settings.\[my_val\].type = stringlist

    ![Screenshot of a site setting field of type stringlist](../../Images/ManualScreenshots/SiteHandling/SiteSettingsTypeStringlist.png)

    The value must be an array whose array key starts at 0 and increases by 1 per element. This sequence is
    checked using the internal PHP method array_is_list in order to prevent named array keys from the outset.
    This also means that comma-separated lists cannot be converted here.

    The `string` type is executed for each array entry.

    **EXT:my_extension/Configuration/Sets/MySet/settings.definitions.yaml**

    ```yaml
    settings:
      example.types.stringlist:
        type: stringlist
        default:  ['Dog', 'Cat', 'Bird', 'Spider']
        category: Example.types
        label: 'Type stringlist'
        description: 'The value must be an array whose array keys start at 0 and
        increase by 1 per element. The list in this type is derived from the
        internal PHP method array_is_list() and has nothing to do with the fact
        that comma-separated lists can also be converted here.

        The `string` type is executed for each array entry.'

    ```

-   **color**

    -   *Type:* string
    -   *Path:* settings.\[my_val\].type = color

    ![Screenshot of a site setting field of type color](../../Images/ManualScreenshots/SiteHandling/SiteSettingsTypeColor.png)

    Checks whether the specified string can be interpreted as a color code.
    Entries starting with `rgb`, `rgba` and `#` are permitted here.

    For `#` color codes, for example, the system checks whether they
    have 3, 6 or 8 digits.

    **EXT:my_extension/Configuration/Sets/MySet/settings.definitions.yaml**

    ```yaml
    settings:
      example.types.color:
        type: color
        default: '#FF8700'
        category: Example.types
        label: 'Type color'
        description: 'Checks whether the specified string can be interpreted as a
        color code. Entries starting with `rgb`, `rgba` and `#` are permitted here.

        For `#` color codes, for example, the system checks whether they
        have 3, 6 or 8 digits.'

    ```

-   **page**

    -   *Type:* string
    -   *Path:* settings.\[my_val\].type = page

    <!-- TODO: no Markdown rendering for "versionadded" -->

    This type has been added to compensate the missing UX functionality
    when using type=int to reference page records.
    Integrators had no way to look up page ids while editing site
    settings. This type adds an integrated page browser that solves this
    problem.![Screenshot of a site setting field of type page](../../Images/ManualScreenshots/SiteHandling/SiteSettingsTypePage.png)

    Checks whether the value is already an integer or can be interpreted as an
    integer. If yes, the string is converted into an integer.

    Additionally renders a page browser in the settings editor to allow the
    user to select a page for a specific setting, while still displaying the
    UID in the field.

    **EXT:my_extension/Configuration/Sets/MySet/settings.definitions.yaml**

    ```yaml
    settings:
      example.types.page:
        type: page
        default: 0
        category: Example.types
        label: 'Example page'
        description: 'Page id which can be supplied as an integer or a string.'

    ```

## Translating labels and descriptions for settings {#site-settings-definition-translation}

To translate the labels and descriptions for the settings you have defined in
`settings.definition.yml`, remove the `label` entry from there and create a
`labels.xlf` file in the same directory.

The key of the translation unit must be the key of the setting.
For example, the label of the setting is simply `label` in the XLF file.

**Example**

**Example label definition in labels.xlf**

```xml
<trans-unit id="label">
    <source>My Custom Set</source>
</trans-unit>
```

> [!IMPORTANT]
> To translate the labels of your settings using Crowdin, you need to adjust
> your extension's
> [Crowdin configuration file](https://docs.typo3.org/permalink/t3coreapi:crowdin-extension-integration-github-configure@13.4).

### Translating category labels {#site-settings-definition-translation-category}

To translate category labels and descriptions, use the following format:

**Example category label definitions**

```xml
<trans-unit id="categories.mycustomcategory">
    <source>My Custom Category</source>
</trans-unit>

<trans-unit id="categories.description.mycustomcategory">
    <source>Description of My Custom Category</source>
</trans-unit>
```

### Translating settings labels and descriptions {#site-settings-definition-translation-labels}

To translate the label and description of a specific setting, use this structure:

**Example setting label definitions**

```xml
<trans-unit id="settings.mycustomsetting">
    <source>My Custom Setting</source>
</trans-unit>

<trans-unit id="settings.description.mycustomsetting">
    <source>My Custom Setting description</source>
</trans-unit>
```

### Translations for other languages {#site-settings-definition-translation-languages}

To provide translations in another language, use the two-letter language prefix
in the filename. For example:

`de.labels.xlf`