# Funnel

The `Funnel` component allows visualizing of data in a funnel structure, for example, a conversion funnel on a website. The funnel can be configured to display horizontally (see below) or vertically.

<figure><img src="https://1582137130-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkTYtq8XZyg79paoHbd93%2Fuploads%2Fm9XBfjgmFSN1ttOtqzO2%2Fimage.png?alt=media&#x26;token=0d20e5d0-ccc9-4e00-a2b2-eb9b3e5fd868" alt=""><figcaption><p>Funnel example</p></figcaption></figure>

### Data structure

The `Funnel` component can be used to display a single group of data, or multiple data series that flow through the same funnel steps. Both the data, as well as colors are configured via the "Data" configuration property.

It expects a specific JSON structure, which is defined as follows:

```typescript
interface FunnelData {
    colors: Array<string | string[]>;
    labels: string[];
    subLabels?: string[] | null;
    values: number[] | number[][];
}
```

This data structure covers multiple scenarios on how the `Funnel` can be used.

Let us firstly explore the different properties of the JSON structure, using the conversion funnel example above. The JSON data for such a funnel looks as follows:

```typescript
{
  "labels": ["Impressions", "Add To Cart", "Buy"],
  "subLabels": ["Direct", "Social Media", "Ads"],
  "colors": ["#6389E9", "#8DA7EE", "#B5C6F1"],
  "values": [
    [12000, 15000, 24000],
    [5700, 6400, 7800],
    [620, 750, 960]
  ]
}
```

In the example above, there are multiple "data series", that are differentiated by color. Furthermore, the user can explore the values of each series by hovering over the particular funnel step.

<figure><img src="https://1582137130-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkTYtq8XZyg79paoHbd93%2Fuploads%2FJuoMMXTAXJwp9oJLf7Yr%2FScreen%20Cast%202022-10-28%20at%2012.41.54%20PM.gif?alt=media&#x26;token=162944ab-d7f6-4b56-8d25-bc83154c765d" alt=""><figcaption><p>Exploring series values by hover</p></figcaption></figure>

There are three funnel steps ("Impressions", "Add to Cart", "Buy") and there are three distinct data series for this funnel ("Direct", "Social Media", "Ads"). Each data series has a dedicated set of values and a color.&#x20;

* **labels**: This array defines the title of each funnel step. It is displayed at the top (horizontal direction) or on the left (vertical direction), where the data values and percentages are also visualized.
* **subLabels**: This array contains the titles of the data series, which are displayed on hover. This property is optional, i.e. nothing is rendered on hover in case it is omitted.
* **colors**: This array contains a color for each data series. The number of colors must always exactly match the number of data series, i.e. the length of the `subLabels` array (if provided), and the length of each array in `values`. The values in this array can be any valid CSS color, like for example `'red'`, `'#6389E9'` or `'rgba(0, 0, 127, 0.8)'`.
* **values**: Holds all values to be displayed in the funnel. In case there are multiple data series, this will be an array of arrays, while displaying a single set of values can be achieved with a flat array of numbers.

When not using multiple data series, the structure can look much simpler:

```typescript
{
  "labels": ["Impressions", "Add To Cart", "Buy"],
  "colors": ["#6389E9"],
  "values": [12000, 5700, 620],
}
```

This renders a simple funnel with only a single set of values:

<figure><img src="https://1582137130-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkTYtq8XZyg79paoHbd93%2Fuploads%2F0BDColRVmUNBklO0qiR3%2Fimage.png?alt=media&#x26;token=0af3fb92-985d-4731-9aaa-2dbab23679e7" alt=""><figcaption><p>Basic funnel with a single set of values</p></figcaption></figure>

### Gradients

You may have noticed that the `colors` property of the funnel data structure can be an "array of arrays of strings". The purpose of this is to provide the ability for color gradients within a data series. Change the example from the previous section as follows:

```typescript
{
  "labels": ["Impressions", "Add To Cart", "Buy"],
  "subLabels": ["Direct", "Social Media", "Ads"],
  "colors": [
    ["#FFB178", "#FF78B1", "#FF3C8E"],
    ["#A0BBFF", "#EC77FF"],
    "#A0F9FF"
  ],
  "values": [
    [12000, 15000, 24000],
    [5700, 6400, 7800],
    [620, 750, 960]
  ]
}
```

This renders the following funnel with color gradients:

<figure><img src="https://1582137130-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkTYtq8XZyg79paoHbd93%2Fuploads%2FYnOrXGcHc0SSEdxWAuuS%2Fimage.png?alt=media&#x26;token=0c41ec12-009a-478d-b745-e1e052e7fcaa" alt=""><figcaption><p>Funnel with gradients</p></figcaption></figure>

When working with gradients in the `colors` property, consider the following:

* A gradient can consist of more than two colors. You can provide as many colors as you like, and the gradient will linearly transition through the provided colors in the provided order.
* You can freely mix gradients and fixed colors. In the example above, the first two data series are visualized with a gradient, while the third series uses the fixed color `"#A0F9FF"`

{% hint style="info" %}
In case of a single data series, there is no need to provide an array of arrays to the `colors` property, but it must be a flat array of strings. This means, that you don't provide something like `[["#A0BBFF", "#EC77FF"]]`, but instead: `["#A0BBFF", "#EC77FF"]`
{% endhint %}

### Properties

The `Funnel` component offers the following configuration properties.

<table><thead><tr><th width="158">Property</th><th width="159">Type</th><th width="161">Default value</th><th>Behavior</th></tr></thead><tbody><tr><td>Data</td><td><code>object</code></td><td>Conversion funnel example, as shown above</td><td>Determines the values, labels and colors of the funnel displayed. <a href="#data-structure">Learn more</a></td></tr><tr><td>Direction</td><td><code>'horizontal' | 'vertical'</code></td><td><code>'horizontal'</code></td><td>Determines whether to render the funnel horizontally or vertically.</td></tr><tr><td>Display percent</td><td><code>boolean</code></td><td><code>true</code></td><td>Whether the percentages of each step should be displayed in the header or not. These percentages are always calculated against the value of the first step, i.e. against the "funnel entry". There is currently no way to change this logic.</td></tr></tbody></table>

### Events

The `Funnel` component does not offer any UI events.&#x20;

### API

The `Funnel` exposes the following API in the JavaScript runtime environment.

<table><thead><tr><th width="271">Property / Function</th><th width="210">Type</th><th>Behavior</th></tr></thead><tbody><tr><td><code>data</code></td><td><code>object</code></td><td>Provides the currently displayed funnel data. <a href="#data-structure">Learn more</a></td></tr><tr><td><code>displayPercent</code></td><td><code>boolean</code></td><td>Provides the current value of the "Display percent" property</td></tr><tr><td><code>direction</code></td><td><code>'horizontal' | 'vertical'</code></td><td>Provides the current value of the "Direction" property</td></tr><tr><td><code>setData(data)</code></td><td><code>(data: FunnelData) => void</code></td><td>Updates the funnel data. The provided object must match the <code>FunnelData</code> interface. <a href="#data-structure">Learn more</a></td></tr><tr><td><code>setDisplayPercent(value)</code></td><td><code>(value: boolean) => void</code></td><td>Sets the value of the "Display percent" property to the provided boolean value.</td></tr><tr><td><code>setDirection(value)</code></td><td><code>(value: 'horizontal' | 'vertical') => void</code></td><td>Sets the value of the "Direction" property to the provided value. Throws an error in case the value is not either <code>'horizontal'</code> or <code>'vertical'</code>.</td></tr></tbody></table>