# @controls reference

While it's possible to [build controls using the Basic Editor](/guides/controls.md#add-controls-through-the-basic-editor), using the [Advanced Editor](/overview/user-interfaces/view-editors.md#advanced-editor) is the only way to unlock the full flexibility of controls. This guide lists each `property` that can be used in the Advanced Editor, each possible `value` the properties can accept, and which `@controls` can recognize the properties and values.

There are two reference tables in this guide—the first lists properties for **static** controls (nothing happens when map readers click on these controls), and the second lists properties for **interactive** controls (map readers can interact with the map by clicking on these controls).

All values are unitless.

If you find a property or a value that's not documented here, [let us know](mailto:support@kumu.io)!

[Jump to the reference for interactive controls](#interactive-controls).

## Static controls

<table><thead><tr><th>Property</th><th>Description</th><th>Valid Values</th><th data-type="checkbox">Legend</th><th data-type="checkbox">Image</th><th data-type="checkbox">Label</th><th data-type="checkbox">Text</th><th data-type="checkbox">Title</th><th data-type="checkbox">SNA Dashboard</th></tr></thead><tbody><tr><td><code>background-color</code></td><td>Defines background color of control</td><td><code>color</code></td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td></tr><tr><td><code>color</code></td><td>Defines color of control's text</td><td><code>color</code></td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td></tr><tr><td><code>font-family</code></td><td>Defines font family of control's text</td><td><code>family-name</code> <code>generic-family</code></td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td></tr><tr><td><code>font-size</code></td><td>Defines size of control's text</td><td><code>number</code></td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td></tr><tr><td><code>font-style</code></td><td>Defines style of control's text</td><td><code>normal</code> <code>italic</code></td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td></tr><tr><td><code>font-weight</code></td><td>Defines weight of control's text</td><td><code>number</code></td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td></tr><tr><td><code>height</code></td><td>Defines height of control</td><td><code>number</code></td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td></tr><tr><td><code>margin</code></td><td>Defines space between the control and other controls on the map</td><td><code>number</code></td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td></tr><tr><td><code>metrics</code></td><td>Defines which metrics will be included in the dashboard</td><td><code>element-count</code> <code>connection-count</code> <code>density</code> <code>reciprocity</code> <code>diameter</code> <code>average-degree</code> <code>average-path-length</code></td><td>false</td><td>false</td><td>false</td><td>false</td><td>false</td><td>false</td></tr><tr><td><code>opacity</code></td><td>Defines opacity of the control</td><td><code>0..1</code></td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td></tr><tr><td><code>padding</code></td><td>Defines space between the control's border and its contents</td><td><code>number</code></td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td></tr><tr><td><code>src</code></td><td>Defines the source of the image</td><td><code>url</code></td><td>false</td><td>true</td><td>false</td><td>false</td><td>false</td><td>false</td></tr><tr><td><code>text-align</code></td><td>Defines alignment of text within the control</td><td><code>center</code> <code>left</code> <code>right</code></td><td>false</td><td>false</td><td>true</td><td>true</td><td>true</td><td>false</td></tr><tr><td><code>value</code></td><td>Any plain text string. Markdown and some HTML allowed.</td><td><code>string</code></td><td>false</td><td>false</td><td>true</td><td>true</td><td>true</td><td>false</td></tr><tr><td><code>width</code></td><td>Defines width of control</td><td><code>number</code></td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td></tr></tbody></table>

## Interactive controls

<table><thead><tr><th>Property</th><th>Description</th><th>Valid Values</th><th data-type="checkbox">Filter</th><th data-type="checkbox">Showcase</th><th data-type="checkbox">Focus</th><th data-type="checkbox">Cluster</th><th data-type="checkbox">Tagged Timeline</th><th data-type="checkbox">View Toggle</th></tr></thead><tbody><tr><td><code>as</code></td><td>Defines how the control is presented</td><td><code>labels</code> <code>buttons</code> <code>dots</code> <code>dropdown</code></td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td></tr><tr><td><code>background-color</code></td><td>Defines background color of control</td><td><code>color</code></td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td></tr><tr><td><code>by</code></td><td>Defines the field to filter, showcase, or cluster by</td><td><code>''Field Name'</code></td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td></tr><tr><td><code>color</code></td><td>Defines color of control's text (labels, placeholders, and summaries only)</td><td><code>color</code></td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td></tr><tr><td><code>default</code></td><td>Defines which options should be selected by default</td><td><code>none</code> <code>show-all</code> <code>select all</code> <code>''field value 1', 'field value 2',...</code></td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td></tr><tr><td><code>except</code></td><td>Allows you to remove field values from the available choices</td><td><code>''field value 1', 'field value 2',...</code></td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td></tr><tr><td><code>font-family</code></td><td>Defines font family of control's text (labels, placeholders, and summaries only)</td><td><code>family-name</code> <code>generic-family</code></td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td></tr><tr><td><code>font-size</code></td><td>Defines size of control's text (labels, placeholders, and summaries only)</td><td><code>number</code></td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td></tr><tr><td><code>font-style</code></td><td>Defines style of control's text (labels, placeholders, and summaries only)</td><td><code>normal</code> <code>italic</code></td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td></tr><tr><td><code>font-weight</code></td><td>Defines weight of control's text (labels, placeholders, and summaries only)</td><td><code>number</code></td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td></tr><tr><td><code>height</code></td><td>Defines height of control</td><td><code>number</code></td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td></tr><tr><td><code>label</code></td><td>Adds a label above the control</td><td><code>'My Label'</code></td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td></tr><tr><td><code>margin</code></td><td>Defines space between the control and other controls on the map</td><td><code>number</code></td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td></tr><tr><td><code>mode</code></td><td>Controls how the selection is showcased. <code>normal</code> is the default and showcases the selection plus any connections between the showcased elements. <code>loose</code> showcases the selection plus neighboring elements. <code>strict</code> only showcases the selection itself.</td><td><code>normal</code> <code>loose</code> <code>strict</code></td><td>false</td><td>true</td><td>false</td><td>false</td><td>false</td><td>false</td></tr><tr><td><code>multiple</code></td><td>Controls whether more than one option can be selected at a time</td><td><code>true</code> <code>false</code> <code>match-all</code></td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td></tr><tr><td><code>only</code></td><td>Allows you to explicitly define which field values should be included as available choices</td><td><code>''field value 1', 'field value 2',...</code></td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td></tr><tr><td><code>opacity</code></td><td>Defines opacity of the control</td><td><code>0..1</code></td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td></tr><tr><td><code>options</code></td><td>Allows you to explicitly define which options should be included as available choices</td><td><code>''partial-view-1', 'partial-view-2',...</code></td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td></tr><tr><td><code>out</code></td><td>Defines the level of connections you'd like to see (out 1: first-degree only, out 2: first- and second-degree, etc.)</td><td><code>number</code></td><td>false</td><td>false</td><td>true</td><td>false</td><td>false</td><td>false</td></tr><tr><td><code>padding</code></td><td>Defines space between the control's border and its contents</td><td><code>number</code></td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td></tr><tr><td><code>placeholder</code></td><td>The text to display when nothing is selected<br>(for <code>as: dropdown</code> only)</td><td><code>string</code></td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td></tr><tr><td><code>range</code></td><td>Defines the years that should be included</td><td><code>year..year</code></td><td>false</td><td>false</td><td>false</td><td>false</td><td>true</td><td>false</td></tr><tr><td><code>summary</code></td><td>Summarizes the options that have been selected<br>(for <code>as: dropdown</code> only)</td><td><code>string</code></td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td></tr><tr><td><code>target</code></td><td>Defines which items will be affected by the control</td><td><code>selector</code></td><td>true</td><td>false</td><td>false</td><td>false</td><td>false</td><td>false</td></tr><tr><td><code>width</code></td><td>Defines width of control</td><td><code>number</code></td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td></tr></tbody></table>


---

# 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.kumu.io/overview/advanced-editor-hub/controls-reference.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.