> For the complete documentation index, see [llms.txt](https://docs.roomle.com/rubens/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.roomle.com/rubens/rubens-products/rubens-configurator/recipes/add-product-variants.md).

# Add product variants

If you have different variants of your product and want to show them to your webshop users it makes sense to activate the variants feature. Variants could be products with different materials but we advise to use the variants feature for structural different product configurations, e.g.: the customer can start with a L-sofa but you have various different types of sofas or you start with a lowboard shelf but the same collection also has a highboard.

In other words, the variants feature should help the user of your webshop to explore the collection of a product. Of course the user could configer from on variation to the next variation but this is time consuming and reduces the chance that the user discovers all meaningful options.

To enable the variation feature some steps are necessary:

The first thing involves data-setup in [Rubens Admin](https://admin.roomle.com/).

* you need to create different variants of your base product
* you need to assign the variants to a tag

After that you can create a "variants map", which is basically a JSON key/value pair. The key is the ID of the root component and the value is the ID of the tag, an example could look like:

Copy

```javascript
const options = {
  variants: {
    'usm:frame': 'tag_id_usm',
    'vitra:chair': 'tag_id_vitra'
  }
};
```

Now everytime a configuration which is based on the root component `usm:frame` the variants from the tag `tag_id_usm` are loaded and displayed in the configurator. If you change to something which is based on `vitra:chair` the variants from `tag_id_vitra` are loaded. If you load something which is not based on one of them no variants are loaded.

This behaviour is needed that the configurator only shows relevant variants which have something in common with the initial loaded configuration.

Copy

```javascript
const configurator = await RoomleConfiguratorApi.createConfigurator(
  'demoConfigurator',
  document.getElementById('configurator-container'), {
    ...options,
    variants: {
      'usm:frame': 'tag_id_usm',
      'vitra:chair': 'tag_id_vitra'
    }
  },
);
```

When changing a variation the global parameters are applied to the newly loaded variaton. You can try this out in the CodeSandbox below. Just set the color of the shelf to yellow and switch the variant. You will see that the loaded variant is also yellow.

You can achieve the same behavior when you add the option `{applyCurrentGlobalParameters: true}` to `extended.loadConfigurableItemById`, `extended.loadConfigurationById` or `extended.loadConfiguration`

You can test and play around with those settings in [this CodeSandbox](https://codesandbox.io/p/sandbox/getting-started-forked-c988pg).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.roomle.com/rubens/rubens-products/rubens-configurator/recipes/add-product-variants.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.