> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://contentful.com/developers/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://contentful.com/developers/docs/_mcp/server.

# UI Extensions - Parameters

> UI extensions can be parametrized to achieve separation of code and configuration | Understanding parameters | Definitions

## What are parameters?

> **Info**
>
> Parameters can be read by anybody who belongs to a space where your UI extension is installed. It's not secure to use parameters to inject access tokens with access level permitting data manipulation. Read-only tokens can be used but keep in mind their value is not hidden.

It's important to achieve separation of the code that forms your UI extension and the configuration that is used by it. This way it can be shared, reused and reconfigured without any code changes.

Below are some examples of the use cases for parameters:

* Default values.
* Project, category or entity identifiers when loading data from external APIs.
* Slack channel name to post messages to.
* Content types to process (e.g. for publishing content trees).
* Kinds of validation to apply.

The following types of configuration parameters can be set up:

* **Installation parameters** — Are set during installation in a space environment and which can be modified in subsequent configuration updates. Their values are available across all usages of the UI extension in the environment.
* **Instance parameters** — Are set when a space member with access to the content model assigns a UI extension to a [location](/extensibility/ui-extensions/locations). Values provided are available only in the specific location and content type where they were entered.

## Parameter definition

**Parameter definition** is an object constructed as described in the table below.

| Property      | Type and value                                                                                                     | Is required?            | Remarks                                                                                        |
| ------------- | ------------------------------------------------------------------------------------------------------------------ | ----------------------- | ---------------------------------------------------------------------------------------------- |
| `id`          | String                                                                                                             | yes                     | Can contain only letters, numbers and underscores                                              |
| `name`        | String                                                                                                             | yes                     | Human readable name of the parameter                                                           |
| `description` | String                                                                                                             | no                      | Further explanation of the purpose of the parameter                                            |
| `type`        | String, one of `Symbol`, `Enum`, `Number`, `Boolean`                                                               | yes                     | `Enum` parameters hold a predefined list of `Symbol`s                                          |
| `required`    | Boolean                                                                                                            | no, defaults to `false` | Whether the parameter value needs to be provided                                               |
| `default`     | Should match `type`                                                                                                | no                      | Default value to use for the parameter. For `Enum`s it has to be defined on the `options` list |
| `options`     | List of allowed values: `["one", "two"]`; can be a list of `{"value": "Label"}` pairs to provide labels for values | yes                     | Applicable only to `Enum`s. `["x", "y"]` is equivalent to `[{"x": "x"}, {"y": "y"}]`           |
| `labels`      | For `Enum`s: `{"empty": "Choose a value"}`; for `Boolean`s: `{"true": "sí", "false": "no"}`                        | no                      | Used for rendering a form. All labels are optional and have sensible defaults in English       |

## Parameter definition for UI Extensions

Up to 8 instance and 8 installation parameters can be defined as a part of the [`Extension`](/references/content-management-api/overview) entity:

```js
{
  "extension": {
    "name": "My parametrized object editor",
    "fieldTypes": [{type: "Object"}],
    "srcdoc": "<!DOCTYPE html>...",
    "parameters": {
      "installation": [
        {
          "id": "devMode",
          "type": "Boolean",
          "name": "Run in development mode"
        },
        {
          "id": "retries",
          "type": "Number",
          "name": "Number of retries for API calls",
          "required": true,
          "default": 3
        }
      ],
      "instance": [
        {
          "id": "helpText",
          "type": "Symbol",
          "name": "Help text",
          "description": "Help text for a user to help them understand the editor"
        },
        {
          "id": "theme",
          "type": "Enum",
          "name": "Theme",
          "options": [{"light": "Solarized light"}, {"dark": "Solarized dark"}],
          "default": "light",
          "required": true
        }
      ]
    }
  }
}
```

## Set and read parameter values

Instance parameters are set in the [Editor Interface](/references/content-management-api/overview) entity.
Installation parameters are provided as a top-level `parameters` property of the `Extension` entity:

```js
{
  "parameters": {
    "devMode": true,
    "retries": 10
  }
}
```

Values, for both instance and installation parameters, can be read with the [App SDK](/extensibility/app-framework/sdk#configuration-of-an-extension-with-parameters):

```js
init((sdk) => {
  console.log(sdk.parameters.instance);
  console.log(sdk.parameters.installation);
});
```

> **Info**
>
> Both `instance` and `installation` are guaranteed to be an empty object if values were not provided.

## Next steps

* [Hosting of UI Extensions.](/extensibility/ui-extensions/hosting/)