controls-reference.md

@controls reference

While it's possible to build controls using the Basic Editor, using the 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!

Jump to the reference for interactive controls.

Static controls

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

Interactive controls

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