### Elegantly visualize a group of options in the DatoCMS Editor using colors, images, and more.

[

**This is a Community Plugin!** Learn how create your own plugin, or copy and remix existing ones in our documentation

](https://www.datocms.com/docs/plugin-sdk/introduction.md)

## Visual Select — a DatoCMS Plugin

Elegantly visualize a group of options in the DatoCMS Editor using colors, images, and more.

(Image content)

---

## Configuration

This plugin is designed to be used on a per-field basis. To get started, add a single-string text field to any model or block, and under the presentation tab change the field editor from "Text input" to "Visual Select".

(Image content)

### JSON Data Structure

Each field requires a JSON configuration object. This object has 2 key fields — the first is `extends` and the second is `options`.

To understand the behaviour of `extends`, see the [Global Presets](https://www.datocms.com/marketplace/plugins/i/datocms-plugin-visual-select.md#global-presets) section below.

`options` represents each visual option displayed to the editor, as well the underlying value returned by the API. There are 4 required fields on each option:

| Key | Value | Description |
| --- | --- | --- |
| `name` | `string` | The label displayed in the editor |
| `type` | `string` | The visualization type, see table below |
| `display` | `string` | The visualization display value, see table below |
| `value` | `string` | The value returned by the API |

#### Visualization displays

| Type | Display | Example |
| --- | --- | --- |
| `color` | `hex` | `#bada55` |
| `image` | `url` | `https://example.com/my-icon.svg` |

### Visualization

There is also a third optional field you can add called `presentation`

`presentation` Is an object representing how the options should be displayed. It has 3 optional fields:

| Key | Value | Description |
| --- | --- | --- |
| `type` | `string` | The presentation type, can be either `grid` or `carousel` |
| `columns` | `integer` | The number of columns, used only if the type `grid` was selected |
| `width` | `string` | The width of each option item, used only if the type `carousel` was selected |

### Example configuration

```json
{  "options": [    {      "name": "Green",      "type": "color",      "display": "#bada55",      "value": "text-brand-green"    },    {      "name": "Yellow",      "type": "color",      "display": "#fcba03",      "value": "text-brand-yellow"    }  ],  "presentation": {    "type": "carousel",    "width": "300px"  }}
```

## Global Presets

You'll often have a collection of options that you want to make available across multiple different models or blocks. Instead of repeating the same configuration object on each field, you can make use of the global presets functionality.

To supply a global presets object, navigate to the **Visual Select** plugin settings under ***Settings \> Plugins \> Visual Select***.

(Image content)

### JSON Data Structure

The JSON configuration for global presets is a simple dictionary object, where each entry is an array of options following the same structure as those used on individual fields.

To make use of a global preset, first define the dictionary object in the plugin settings:

```json
{  "brandColors": [    {      "name": "Green",      "type": "color",      "display": "#bada55",      "value": "text-brand-green"    },    {      "name": "Yellow",      "type": "color",      "display": "#fcba03",      "value": "text-brand-yellow"    }  ]}
```

and then in an individual field's configuration object, use the `extends` key:

```json
{  "extends": ["brandColors"]}
```

You can extend multiple presets if required, and you can also supply additional options:

```json
{  "extends": ["brandColors"],  "options": [    {      "name": "Blue",      "type": "color",      "display": "#00d0ff",      "value": "text-specials-blue"    },    {      "name": "Purple",      "type": "color",      "display": "#8b05eb",      "value": "text-specials-purple"    }  ]}
```

The example above would produce the following editor visualization (where `Green` and `Yellow` are coming from the `brandColors` preset, and `Blue` and `Purple` are from the additional options supplied):

(Image content)