# Trellis layout

> Trellis is only available for Area, Bar, Column, Filler Gauge, Line, Pie, Scatter, and Single value visualizations.

Organize your search results with the trellis layout for a holistic view of your data. Trellis layout visualizes your search results by separating each value field or aggregation.

The search in the following example returns customer purchases by product category. Applying a trellis layout creates a view of each product category as its own visualization.

`index="sample-data" | stats count by productName`

![](./src/common/docs/images/trellis-intro.png)

## Create a trellis layout

Configure your visualization for the trellis layout by adding the `splitByLayout:trellis` option in the `options` stanza. You might need to adjust the sizing of your trellis layout to fit your page.

### Trellis layout configuration UI

Customers with access to a Unified Dashboard Framework (UDF) **Edit** mode can create the trellis layout using the following steps. If you’re not using UDF, skip to step 4.

1. Select a visualization that supports trellis (Area, Bar, Column, Filler Gauge, Line, Pie, Scatter, Single value) using the visual editor by clicking the **Add Chart** dropdown menu in the editing toolbar.
2. Select the visualization on your dashboard so that it's highlighted with the blue editing outline.
3. Set up a new data source by adding selecting **+ Create Search** and adding a search to the **Search query** window. Or, select an existing data source under the **Search**, **Saved Search**, or **Chain Search** dropdown lists.
4. Activate the trellis layout by toggling on **Trellis Layout** in the **Data display** section of the Configuration panel.

## Configurations for trellis layout

Additionally, you can add the following trellis configurations to the `options` stanza for further customization.

```markup
| Option                 | Type    | Default                         | Description                                                                                                                                                                                                                                                                                                                        |
| ---------------------- | ------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| splitByLayout          | string  | off                             | Specify the layout method to display the visualization, which splits the data into individual visualizations based on a specific category. The available values are off and trellis.                                                                                                                                               |
| trellisBackgroundColor | string  | > themes.defaultBackgroundColor | Specify the background color of the whole panel in the trellis layout display. For example, “#FF0000”. You can use a hexadecimal code to apply the color. The default for Enterprise light is #ffffff. The default for Enterprise dark is #000000. The default for Prisma dark is #0b0c0e.                                         |
| trellisColumns         | number  | n/a                             | Specify the number of columns in a trellis layout container. For example, six columns allow six visualizations per row. Rows populate to accommodate the total number of visualizations. If no column number is specified, the number of columns is automatically set based on the value specified for trellisMinColumnWidth.      |
| trellisMinColumnWidth  | number  | 100                             | Specify the minimum width, in pixels, of each visualization in the trellis container. If you resize the window or panel, you can view the remaining visualizations by scrolling.                                                                                                                                                   |
| trellisPageCount       | number  | 20                              | Specify the maximum number of visualizations to display on a single page in the trellis container. The remaining visualizations paginate accordingly.                                                                                                                                                                              |
| trellisRowHeight       | number  | 70                              | Specify each visualization's height, in pixels, in the trellis container. If you resize the window or panel, you can view the remaining visualizations by scrolling.                                                                                                                                                               |
| trellisSharedScale     | boolean | true                            | If applicable, specify whether all visualizations will share the same scale in the trellis container. This only applies to Area, Bar, Column, Scatter and Line chart.                                                                                                                                                                       |
| trellisSortBy          | string  | result                          | Specify the sort method for the individual visualizations in the trellis container. See the Trellis sort options section below for supported values per visualization type.                                                                                                                                                       |
| trellisSortOrder       | string  | ascending                       | Specify the sort order for the individual visualizations in the trellis container. The available values are ascending and descending.                                                                                                                                                                                             |
| trellisSplitBy         | string  | n/a                             | If applicable, specify the column's field name with categories used or aggregations to split the data into individual visualizations for trellis display. If you use an SPL `timechart` command, this might default to the SPL `by` clause field. If you use an SPL `chart` command, this might default to the first string field. |
```

## Overview of data-splitting logic

The trellis layout splits data visualizations based on the SPL commands and associated metadata or configurations provided. The data-splitting logic defaults to SPL commands and associated metadata first, then option configurations. If you apply configuration options, any of those options could impact how the logic behaves with SPL commands or data field types. The following examples show different scenarios of data-splitting logic.

If your application has SPL support, the following are examples of how SPL searches impact the trellis layout data-splitting logic. If your application doesn’t have SPL, you might need to restructure your data and use the `trellisSplitBy` option to achieve similar results to the following examples.

### Split data with the timechart command

When using the SPL `timechart` command, the trellis layout defaults to an associated `by` clause. The following example shows how the trellis layout categorizes each Single value visualization by product name as a result of the SPL search `index="sample-data" | timechart count by productName`.

![](./src/common/docs/images/trellis-timechart.png)

![](./src/common/docs/images/trellis-timechart-table.png)

#### Source code

```
import React from 'react';
import { FeatureFlagContextProvider } from '@splunk/visualization-context/FeatureFlagContext';
import SingleValue from '@splunk/visualizations/SingleValue';

export default () => (
    <FeatureFlagContextProvider value={{ visualizations_enableTrellis: true }}>
      <SingleValue
         options={{
            splitByLayout: 'trellis',
         }}
         dataSources={{
            primary: {
               data: {
                  columns: [
                     [
                        '2023-03-21T00:00:00.000+00:00',
                        '2023-03-22T00:00:00.000+00:00',
                        '2023-03-23T00:00:00.000+00:00',
                        '2023-03-24T00:00:00.000+00:00',
                        '2023-03-25T00:00:00.000+00:00',
                        '2023-03-26T00:00:00.000+00:00',
                        '2023-03-27T00:00:00.000+00:00',
                        '2023-03-28T00:00:00.000+00:00',
                     ],
                     ['80', '271', '263', '289', '263', '304', '268', '236'],
                     ['62', '265', '263', '289', '263', '304', '261', '205'],
                     ['51', '291', '263', '289', '263', '304', '268', '211'],
                     ['77', '334', '263', '289', '263', '304', '301', '230'],
                  ],
                  fields: [
                     {
                        name: '_time',
                     },
                     {
                        name: 'Dream Crusher',
                     },
                     {
                        name: 'Final Sequel',
                     },
                     {
                        name: 'Fire Resistance Suit of Provolone',
                     },
                     {
                        name: 'Grand Theft Scooter',
                     },
                  ],
               },
               meta: {},
            },
         }}
      />
    </FeatureFlagContextProvider>
);

```

### Split data with the chart or stats commands

The trellis layout defaults to the first string field when using the SPL `chart` or `stats` command with one `by` clause. The following example shows how the trellis layout categorizes each visualization, in this case Single value, by the `productName` column as a result of the SPL search `index="sample-data" | chart count by productName`.

![](./src/common/docs/images/trellis-chart-stats.png)

![](./src/common/docs/images/trellis-chart-stats-table.png)

#### Source code

```
import React from 'react';
import { FeatureFlagContextProvider } from '@splunk/visualization-context/FeatureFlagContext';
import SingleValue from '@splunk/visualizations/SingleValue';

export default () => (
    <FeatureFlagContextProvider value={{ visualizations_enableTrellis: true }}>
      <SingleValue
         options={{
            splitByLayout: 'trellis',
            trellisSplitBy: 'productName',
         }}
         dataSources={{
            primary: {
               data: {
                  columns: [
                     ['Benign Space Debris', 'Curling 2014', 'Dream Crusher', 'Final Sequel'],
                     ['1309', '1346', '1974', '1766'],
                  ],
                  fields: [
                     {
                        name: 'productName',
                     },
                     {
                        name: 'count',
                     },
                  ],
               },
               meta: {},
            },
         }}
      />
    </FeatureFlagContextProvider>
);

```

### Split specific data with the trellisSplitBy option

If you don't want to rely on the default data-splitting logic, you can split your data by a specific field name using the 'trellisSplitBy' option. For example, you can split the data by price if you have multiple products with different price points. Using `trellisSplitBy` overrides the logic to split the data by product name.

The following example sets `trellisSplitBy: price` with the SPL search `index="sample-data" | chart count by productName, price`. `"sample-data"` is a lookup file available for upload in the [Search Tutorial](https://docs.splunk.com/Documentation/Splunk/latest/SearchTutorial/WelcometotheSearchTutorial) of the _Search Tutorial_ manual.

![](./src/common/docs/images/trellis-split-by.png)

![](./src/common/docs/images/trellis-split-by-table.png)

#### Source code

```
import React from 'react';
import { FeatureFlagContextProvider } from '@splunk/visualization-context/FeatureFlagContext';
import SingleValue from '@splunk/visualizations/SingleValue';

export default () => (
    <FeatureFlagContextProvider value={{ visualizations_enableTrellis: true }}>
      <SingleValue
         options={{
            backgroundColor: '#BDBDBD',
            splitByLayout: 'trellis',
            trellisSplitBy: 'price',
         }}
         dataSources={{
            primary: {
               data: {
                  columns: [
                     ['Benign Space Debris', 'Curling 2014', 'Dream Crusher', 'Final Sequel'],
                     ['0', '1346', '0', '0', '0', '0'],
                     ['1309', '0', '0', '1766', '0', '0'],
                     ['0', '0', '0', '0', '0', '0'],
                  ],
                  fields: [
                     {
                        name: 'productName',
                     },
                     {
                        name: '19.99',
                     },
                     {
                        name: '24.99',
                     },
                     {
                        name: '26.99',
                     },
                  ],
               },
               meta: {},
            },
         }}
      />
    </FeatureFlagContextProvider>
);

```

### Configure trellisSplitBy with aggregations

Aggregations are categories specified by field name prefixes. For example, avg(price) is an aggregation of the average price, and max(price) is an aggregation of the maximum price. You can split your data by aggregations using the `trellisSplitBy` option.

The following example sets `trellisSplitBy` aggregations with the SPL search `index="sample-data" | timechart avg(price), max(price)`.

![](./src/common/docs/images/trellis-aggregations.png)

![](./src/common/docs/images/trellis-aggregations-table.png)

#### Source code

```
import React from 'react';
import { FeatureFlagContextProvider } from '@splunk/visualization-context/FeatureFlagContext';
import SingleValue from '@splunk/visualizations/SingleValue';

export default () => (
    <FeatureFlagContextProvider value={{ visualizations_enableTrellis: true }}>
      <SingleValue
         options={{
            splitByLayout: 'trellis',
            trellisSplitBy: 'aggregations',
         }}
         dataSources={{
            primary: {
               data: {
                  columns: [
                     [
                        '2023-03-21T00:00:00.000+00:00',
                        '2023-03-22T00:00:00.000+00:00',
                        '2023-03-23T00:00:00.000+00:00',
                        '2023-03-24T00:00:00.000+00:00',
                        '2023-03-25T00:00:00.000+00:00',
                        '2023-03-26T00:00:00.000+00:00',
                        '2023-03-27T00:00:00.000+00:00',
                        '2023-03-28T00:00:00.000+00:00',
                     ],
                     ['22.64029940119746', '21.768596847991684', '21.885890410958826', '21.936683354193125'],
                     ['49.99', '49.99', '49.99', '49.99'],
                  ],
                  fields: [
                     {
                        name: '_time',
                     },
                     {
                        name: 'avg(price)',
                     },
                     {
                        name: 'max(price)',
                     },
                  ],
               },
               meta: {},
            },
         }}
      />
    </FeatureFlagContextProvider>
);

```

## Customize trellis columns with trellisMinColumnWidth and trellisColumns

You can customize the width of each visualization in the trellis layout with the `trellisMinColumnWidth` option. By default, `trellisMinColumnWidth` adjusts based on the configuration of the `config.ts` file and the parent panel width.

The following example shows how the trellis layout changes when the default `trellisMinColumnWidth` is updated to `trellisMinColumnWidth: 150`.

![](./src/common/docs/images/trellis-col-1.png)

![](./src/common/docs/images/trellis-col-2.png)

You can customize the number of visualizations to display in a single row of the trellis panel with `trellisColumns`. Visualizations with an undefined `trellisColumns` fill and wrap within the set width of the trellis panel.

The following example shows how visualizations might extend beyond the trellis panel with a `trellisMinColumnWidth: 150` and `trellisColumns: 6`.

![](./src/common/docs/images/trellis-col-3.png)

## Event payload for trellis

When the Trellis layout is enabled, the event payload object includes two additional key-value pairs, along with the existing payload:

1. `trellis.name` - The value set for the `trellisSplitBy` option.
2. `trellis.value` - The specific value used in the title of each Trellis child visualization.

Examples can be found in the Events tab on the Trellis-supported visualizations page.

## Trellis sort options

You can control the order of individual visualizations within the trellis container using the `trellisSortBy` and `trellisSortOrder` options. By default, visualizations are sorted by `result` order in `ascending` direction, which preserves the order returned by the search.

### Sort methods

| Sort method | Description                                                                                                                    |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `result`    | Sort by the original search result order (default). Ascending preserves the order; descending reverses it.                     |
| `name`      | Sort alphabetically by the visualization label (the split-by key). Numeric-aware comparison is used, so "2" sorts before "10". |
| `value`     | Sort by the evaluated major value of each panel. Panels with non-numeric values are placed at the end.                         |
| `trend`     | Sort by the evaluated trend value of each panel. Panels with non-numeric trend values are placed at the end.                   |

### Supported sort methods per visualization type

Not all sort methods are available for every visualization type. The following table shows which `trellisSortBy` values are supported for each visualization.

| Visualization       | `result` | `name` | `value` | `trend` |
| ------------------- | -------- | ------ | ------- | ------- |
| Single Value        | Yes      | Yes    | Yes     | Yes     |
| Single Value Icon   | Yes      | Yes    | Yes     | Yes     |
| Single Value Radial | Yes      | Yes    | Yes     | Yes     |
| Filler Gauge        | Yes      | Yes    | Yes     | No      |
| Marker Gauge        | Yes      | Yes    | Yes     | No      |
| Pie                 | Yes      | Yes    | No      | No      |
| Area                | Yes      | Yes    | No      | No      |
| Line                | Yes      | Yes    | No      | No      |
| Column              | Yes      | Yes    | No      | No      |
| Bar                 | Yes      | Yes    | No      | No      |
| Scatter             | Yes      | Yes    | No      | No      |

### Example

Sort a trellis layout by name in descending order:

```
<SingleValue
    options={{
        splitByLayout: 'trellis',
        trellisSortBy: 'name',
        trellisSortOrder: 'descending',
    }}
    dataSources={dataSources}
/>
```
