# Customize embeds

## Embed Parameters

### Additional panel

{% hint style="info" %}
Applicable to stories only (not tiles).
{% endhint %}

The Additional Panel can be customized to include features like **Annotate and Share**, **Export Data**, and **Send by Email**. To enable or disable these options:

1. Go to the Advanced Configuration of your Toucan application, accessible from the Settings button in the staging bar.
2. Edit the `app_config` file:
   * Set `true` to enable an option or `false` to disable it.

Example: To enable “Annotate & Share,” set: `annotateAndShareEnabled: true`.

{% @arcade/embed url="<https://app.arcade.software/flows/d0GNZAGcABZH2bb5pkjO/view>" flowId="d0GNZAGcABZH2bb5pkjO" %}

**Enabling the Additional Panel in Embeds**

**In an Embedded Story**: Enable the panel options in the application and activate them in the embed modal.

{% @arcade/embed url="<https://app.arcade.software/share/tFw4LQaJOaiXPCtejhPl>" flowId="tFw4LQaJOaiXPCtejhPl" %}

**In an Embedded Dashboard**: Enable the options in the app, then add `&panel=true` in the embed script.

{% code overflow="wrap" %}

```html
<script async src="https://myinstance.toucantoco.com/scripts/embedLauncher.js?id={EMBED_ID}&token={TOKEN}&panel=true" type="text/javascript"></script>
```

{% endcode %}

### Initialize filters values

{% hint style="info" %}
By default, filters load with the default or first value.
{% endhint %}

You can set initial filter values by adding them to the embed URL:

```html
<script async src="https://myinstance.toucantoco.com/scripts/embedLauncher.js?id={EMBED_ID}
&token={TOKEN}&filters.{FILTER_ID}={ENCODED_FILTER_VALUE}" type="text/javascript"></script>
```

`ENCODED_FILTER_VALUE` should be JSON-stringified and URI-encoded, formatted depending on the filter type (single, multiple, or date range).

* single filters (dropdown, hierarchical, single button): a key-value object with keys being dataset columns and values being values in the dataset row
* multiple filters (checkboxes, multiple buttons): an array of single filter values
* date range filters: a key-value object with two optional start and end keys and date values

For example, let's say we have a dataset of movies and whether they pass the [Bechdel test](https://en.wikipedia.org/wiki/Bechdel_test):

| movie\_name            | bechdel\_test | release\_year | director\_nationality |
| ---------------------- | ------------- | ------------- | --------------------- |
| The Social Network     | fails         | 2010          | american              |
| Gran Torino            | fails         | 2008          | american              |
| No Country For Old Men | pass          | 2007          | american              |
| V For Vendetta         | pass          | 2005          | australian            |
| Fight Club             | fails         | 1999          | american              |

and three filters:

* `0953c8d4-c5d0-4f2d-b3ba-e83480c337a3` dropdown on `bechdel_test`
* `2896ad55-4e45-49a1-80c2-00b74ae6d857` date range on `release_year`
* `7e1050e1-5f9f-433a-aeeb-14b47315c218` checkboxes on `director_nationality`

For instance, to display only American or Canadian movies from before 2000 that pass the Bechdel test:

```ts
const url = new URL('https://myinstance.toucantoco.com/scripts/embedLauncher.js');
url.searchParams.set('id', 'ID');
url.searchParams.set('token', 'TOKEN');
url.searchParams.set(
  'filters.0953c8d4-c5d0-4f2d-b3ba-e83480c337a3',
  JSON.stringify({ bechdel_test: 'pass' }),
);
url.searchParams.set(
  'filters.2896ad55-4e45-49a1-80c2-00b74ae6d857',
  JSON.stringify({ end: new Date('2000-01-01') }),
);
url.searchParams.set(
  'filters.7e1050e1-5f9f-433a-aeeb-14b47315c218',
  JSON.stringify({ director_nationality: ['american', 'canadian'] }),
);
console.log(url.href);
```

> Note that [URLSearchParams.prototype.set](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams/set) URI-encodes strings for you, so no need to use [encodeURIComponent](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) on top of it

That would make your script look like this:

```html
<script async src="https://myinstance.toucantoco.com/scripts/embedLauncher.js?id=ID&token=TOKEN&filters.0953c8d4-c5d0-4f2d-b3ba-e83480c337a3=%7B%22bechdel_test%22%3A%22pass%22%7D&filters.2896ad55-4e45-49a1-80c2-00b74ae6d857=%7B%22end%22%3A%222000-01-01T00%3A00%3A00.000Z%22%7D&filters.7e1050e1-5f9f-433a-aeeb-14b47315c218=%7B%22director_nationality%22%3A%5B%22american%22%2C%22canadian%22%5D%7D"
></script>
```

After that initializing your filters, you can programmatically update Filters' values with the [SDK](/visualizations-and-layouts/embedding/embed-sdk.md#setvalue).

### Compact mode

{% hint style="info" %}
Applicable only on stories
{% endhint %}

For stories in small containers or on mobile, stories automatically display in compact mode. To control this manually:

* **Force compact mode**

{% code overflow="wrap" %}

```javascript
<script async src="https://myinstance.toucantoco.com/scripts/embedLauncher.js?id={EMBED_ID}&token={TOKEN}&compact=true" type="text/javascript"></script>
```

{% endcode %}

* **Disable compact mode**

{% code overflow="wrap" %}

```javascript
<script async src="https://myinstance.toucantoco.com/scripts/embedLauncher.js?id={EMBED_ID}&token={TOKEN}&compact=false" type="text/javascript"></script>
```

{% endcode %}

### Display staging version

{% hint style="warning" %}
**Important**

**`staging`** isn't accessible with **`view`** privilege
{% endhint %}

Toucan provides production and staging versions. To display the staging version, add `&stage=staging` to the embed URL:

{% code overflow="wrap" %}

```javascript
<script async src="https://myinstance.toucantoco.com/scripts/embedLauncher.js?id={EMBED_ID}&token={TOKEN}&stage=staging" type="text/javascript"></script>
```

{% endcode %}

### Language Customization (i18n)

Set the language of your embed by adding the `lang` parameter:

{% code overflow="wrap" %}

```javascript
<script async src="https://myinstance.toucantoco.com/scripts/embedLauncher.js?id={EMBED_ID}&token={TOKEN}&lang=en" type="text/javascript"></script>
```

{% endcode %}

## Style Customization

Adjust colors dynamically within the embed script:

<figure><img src="/files/Q3SIE8bjvlUDclu2awTX" alt="color scheme interface"><figcaption></figcaption></figure>

What's interesting is that you can dynamically change those colors through the embed script via the `colors` attribute for webcomponent or query parameter for iframes.

For example:

#### Web Component

<pre class="language-javascript"><code class="lang-javascript">&#x3C;script
<strong>      async
</strong>      src='https://myinstance.toucantoco.com/scripts/embedLauncher.js?id={EMBED_ID}&#x26;token={TOKEN}'
<strong>      colors='{"chart-color-0": "pink"}'
</strong>      type='text/javascript'
>&#x3C;/script>
</code></pre>

#### iFrame

```
<iframe src="https://myinstance.toucantoco.com/embed.html?id={EMBED_ID}&token={TOKEN}&colors={%22chart-color-0%22:%22pink%22}"></iframe>
```

| Themes                                     | Name        | Code                       |
| ------------------------------------------ | ----------- | -------------------------- |
| **Highlights** (Active states, selections) | Emphasis    | `emphasis-color`           |
|                                            | Accent      | `secondary-emphasis-color` |
|                                            | Positive    | `positive-color`           |
|                                            | Warning     | `warning-color`            |
|                                            | Negative    | `negative-color`           |
|                                            | Neutral     | `neutral-color`            |
| **Charts** (Series data)                   | Serie #1    | `chart-color-0`            |
|                                            | Serie #2    | `chart-color-1`            |
|                                            | Serie #3    | `chart-color-2`            |
|                                            | Serie #4    | `chart-color-3`            |
|                                            | Series #x   | `chart-color-x+1`          |
| **Scales** (Quantified data)               | Quartile #1 | `scale-color-0`            |
|                                            | Quartile #2 | `scale-color-1`            |
|                                            | Quartile #3 | `scale-color-2`            |
|                                            | Quartile #4 | `scale-color-3`            |

### Custom Series

You can also customize by data label.

Basically, `tc-series-colors` is a string with data labels in escaped double quotes, followed by the color separate by a space. You can define multiple labels, those groups are separated by commas. The following snippet will color bars with label Level 1 in red and label Level 2 in pink.

```javascript
<script
      async
      src='https://myinstance.toucantoco.com/scripts/embedLauncher.js?id={EMBED_ID}&token={TOKEN}'
      colors='{"tc-series-colors":"\"Level 1\" red, \"Level 2\" pink}"'
      type='text/javascript'
></script>
```

Result as:

<figure><img src="/files/ZlMzOqrRpfO179TYExFq" alt="barchart-witch-dynamic-colors"><figcaption><p>Dynamically change series' colors</p></figcaption></figure>

### Fonts

{% hint style="info" %}
**Note**

Custom CSS is a feature flag that we need to activate. By default the Custom CSS stylesheet is hidden as we’re not providing any support on it. To activate the Custom CSS on your instance please contact us.
{% endhint %}

For fonts, you can use our “Custom CSS” feature that lets you specify CSS rules within the Theme -> Color Scheme Interface. For now, you can only use a font host online. Let us know if it’s a big limitation for you.

Example, with `Lato` font:

<figure><img src="/files/tBaE8BJzSz98lUCEO35N" alt="custom-css-interface"><figcaption></figcaption></figure>

Result as:

<figure><img src="/files/lYGO1Hbn8FA8Auvd9u4I" alt="story-with-lato-font-family"><figcaption></figcaption></figure>

### Deep Customization

Do you dream about having a complete control over the style of your embeds?

[Click here](https://docs.toucantoco.com/embed/integrate/04-embedded-dashboard.html#new-deep-customization) for an example on the Dashboard Builder.


---

# 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-v3.toucantoco.com/visualizations-and-layouts/embedding/integration/customize-embeds.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.