# Setting Parameters

Parameters let you adjust the settings of a configurator instance in two ways:

1. **Initial Parameters via HTML:** You can set an initial configuration by adding a set of parameters directly to the configurator's HTML tag. This approach is useful for loading a predefined configuration when the configurator first loads.
2. **Dynamic Parameters at Runtime:** You can also modify parameters at runtime by calling `setParameter` on the configurator. This method is helpful when building a custom menu or control interface for the configurator.

Note that colormass typically provides the necessary parameter settings, so you do not need to understand the details of the parameter format beyond those two points. The following example adds an initial parameter to the HTML tag by using the `parameters` attribute:

```html
<cm-configurator-main
	template-uuid="9f867cb8-966f-4736-9106-3cacba50b3b4"
	parameters="param(3d23006d-1eb2-47f1-a616-e357695316b8)=material(2d8709e8-d5b9-4028-86b1-d06e8575011b)"
></cm-configurator-main>
```

The same parameter can also be set at runtime:

```html
<script>
	customElements.whenDefined("cm-configurator-main").then(() => {
		cmConfigurator = document.querySelector("cm-configurator-main")
		cmConfigurator.setParameter("3d23006d-1eb2-47f1-a616-e357695316b8", "material", "2d8709e8-d5b9-4028-86b1-d06e8575011b")
	})
</script>
```

### Parameter Format

A configurator parameter is composed of three parts: `id`, `type` and `value`. Values for those parts are usually provided by colormass, but if you have access to the platform, you can also get and edit the available parameters yourself. This is covered in a separate [section below](#parameter-types-and-associated-values).

* **id:** This is a unique identifier for the parameter. This ID is usually platform-generated but can be customized for readability.
* **type:** Specifies how the configurator interprets and processes the value. Different types, like "material" or "config" determine the behavior and application of the parameter within the configurator.
* **value**: The specific value to be used with the parameter. Depending on the type, this value can also be customized for better readability.

The parameter string used to load a given configuration is usually provided by colormass. If you need to change it, the format is as follows:

```
param(id)=type(value)
```

When multiple parameters should be set, they are separated by `&`:

```
param(id1)=type(value1)&param(id2)=type(value2)
```

### Parameter Types and Associated Values

All parameters originate from input elements that were used to build the configurator on the colormass platform. The type of a parameter defines what the configurator will assign to those elements internally. The following types are available:

#### config

This type controls configurations that are also available in the configurator’s menu. It allows to programmatically load a specific configuration variant displayed there. A config parameter is derived from a config group within the configurator’s template, and the values it accepts are the IDs of that group’s config variants (see figures below). Available variants for a config parameter can also be retrieved via `cmConfigurator.getParameterList()`.

<figure><img src="/files/kEEOEEnvTmeQA3la5qHE" alt="" width="563"><figcaption><p>Config group inside the template editor. The ID of the group is part of the parameter ID.</p></figcaption></figure>

<figure><img src="/files/It5aUgA51hOT1ApyHQxn" alt="" width="563"><figcaption><p>Config variant, whose ID can be used in cmConfigurator.setParameter.</p></figcaption></figure>

#### material

This type assigns a material to the configurator, even if it is not available in the configurator’s menu. The required value is a material ID, which you can retrieve via our GraphQL API. Instructions for accessing the API are available [here](/dev/data-exporter/api-access.md), and you can build and test queries directly on the [API test page](https://gql.colormass.com/graphql).

**material-article-id**

This type is used to assign a material by specifying your own in-house ID. The ID must be set up on the details page of the material on the colormass platform:

<figure><img src="/files/l4uJuybap6fy5on0Tvcb" alt="" width="161"><figcaption></figcaption></figure>

### Getting Available Parameters

In order to get the currently available parameters, you can use `getParameterList:`

```html
<script>
    customElements.whenDefined("cm-configurator-main").then(() => {
        cmConfigurator = document.querySelector("cm-configurator-main")

        //Parameters are only available after a configurator was loaded. loadingCompleted is emitted after the initial loading completes
        cmConfigurator.addEventListener("loadingCompleted", (event) => console.log("Current parameters", cmConfigurator.getParameterList()))
        //configurationLoaded is emitted after a new configuration selected by the user was loaded
        cmConfigurator.addEventListener("configurationLoaded", (event) => console.log("Current parameters", cmConfigurator.getParameterList()))
    })
</script>
```

### API Limitations

When creating a custom menu or controls for a configurator, be aware that the configurator’s API currently does not provide information on parameter dependencies. In complex configurators, certain configurations are hidden or shown based on the currently selected variant. Consequently, calls to `cmConfigurator.getParameterList()` may not always list every available parameter. After a parameter with dependencies is changed, subsequent calls to `getParameterList()` may return a different set of parameters.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.colormass.com/dev/configurator/web-components/setting-parameters.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.