Conditional Visibility
Many settings only make sense in combination with others: the color of a border is irrelevant while the border is turned
off, and the options of a chart type only matter while that chart type is selected. With visibleIf and hideIf, the
dashboard builder shows a field or a layout element only while the values of other fields fit.
{
"config": [
{
"name": "show_border",
"label": "Show border",
"type": "checkbox"
},
{
"name": "border_color",
"label": "Border color",
"type": "color",
"visibleIf": {"field": "show_border"}
}
]
}
The border color only shows while the switch "Show border" is on, and appears or disappears as soon as users toggle it.
Where It Works
visibleIf and hideIf can be added to:
- every field, including repeater fields and the fields within a repeater,
- the separator and markdown text,
both in the
configarray and in thelayout, - every layout element:
fieldset,tabs,tab,rowandcolumn.
A hidden layout element hides everything in it. A hidden tab is removed from its tabs, a hidden column frees its
room for the other columns of the row.
| Property | Type | Description |
|---|---|---|
| visibleIf | Condition | Only shows the field or layout element while the condition passes. |
| hideIf | Condition | Hides the field or layout element while the condition passes. |
With both, the field or layout element shows while visibleIf passes and hideIf doesn't. Use whichever reads more
naturally; "hideIf": {"field": "x"} is the same as "visibleIf": {"not": {"field": "x"}}.
Conditional visibility only affects the form in the dashboard builder. A hidden field keeps its value, and the
field hooks still return it. In the example above,
useColorField({field: 'border_color'}) still returns the color users picked before they turned the border off.
The widget has to check the controlling field itself, just like the condition does:
const showBorder = useCheckboxField({field: 'show_border'})
const borderColor = useColorField({field: 'border_color'})
const border = showBorder ? `1px solid ${borderColor}` : 'none'
Conditions
A condition is either a rule, which checks the value of one field, or a combination of other conditions.
| Condition | Passes if |
|---|---|
{"field": "…", …checks} | All checks of the rule pass, see Rules. |
{"all": [conditions]} | All of the conditions pass. |
{"any": [conditions]} | At least one of the conditions passes. |
{"not": condition} | The condition doesn't pass. |
Combinations can be nested as deeply as needed.
Rules
A rule names the field to check and any number of checks. All checks of a rule have to pass. A rule without any
check passes if the value of the field is truthy, which makes {"field": "show_border"} the short form
for "while the switch is on".
The value a rule checks is the value users set, or the defaultValue of the field while it isn't set, e.g. after users
cleared it. This is the value the dashboard builder shows. Pass the same defaultValue to the field hooks in the widget,
so the form and the widget agree on what's selected.
Checks
| Check | Type | Passes if |
|---|---|---|
equals | any | The value equals this one. Objects and lists are compared by their content. |
notEquals | any | The value doesn't equal this one. |
in | array | The value equals one of these. |
notIn | array | The value equals none of these. |
set | boolean | true: the field has a value. false: it has none. See Set and Truthy. |
truthy | boolean | true: the value is truthy. false: it isn't. See Set and Truthy. |
includes | any | The list contains this item, like an option picked in a multi-select. For a text: the text contains this text. |
includesAny | array | The list contains at least one of these items. |
includesAll | array | The list contains all of these items. |
gt | number | The value is a number greater than this one. |
gte | number | The value is a number greater than or equal to this one. |
lt | number | The value is a number less than this one. |
lte | number | The value is a number less than or equal to this one. |
The number checks fail for anything that isn't a number, including a field without a value.
A checkbox that users never touched has no value, but shows as off.
That's why it equals false, even without a defaultValue.
Set and Truthy
| Value | set | truthy |
|---|---|---|
| No value | false | false |
Empty text "", empty list [], empty object {} | false | false |
false, 0 | true | false |
Anything else, like true, "abc", ["a"], a metric | true | true |
set suits fields like a metric or file
field, to show further settings once something was picked. truthy suits switches and numbers.
Which Fields a Condition Can Check
A condition checks fields by their name:
- Fields and layout elements of a widget check the fields of the widget's
config. - Fields within a repeater check the fields of their own repeater item first, and the fields around the repeater second. A field of a repeater item can depend on another field of the same item as well as on a setting of the whole widget.
- The settings of an action only check the other settings of the same action.
A field that doesn't exist has no value: a rule on it passes for "set": false and fails for most other checks.
The CLI reports conditions with unknown checks or a wrong structure, e.g. a typo like equal
instead of equals.
Examples
Depend on a Select
Show settings only for the selected chart type:
{
"config": [
{
"name": "chart_type",
"label": "Chart type",
"type": "button-group",
"defaultValue": "line",
"options": [
{"label": "Line", "value": "line"},
{"label": "Bar", "value": "bar"},
{"label": "Area", "value": "area"}
]
},
{
"name": "line_width",
"label": "Line width",
"type": "slider",
"min": 1,
"max": 10,
"visibleIf": {"field": "chart_type", "in": ["line", "area"]}
},
{
"name": "bar_gap",
"label": "Gap between bars",
"type": "number",
"visibleIf": {"field": "chart_type", "equals": "bar"}
}
]
}
Combine Conditions
Show the color of the min/max labels only while they are picked in a multi-select, and the widget doesn't use the colors of the metric:
{
"name": "min_max_color",
"label": "Min / max color",
"type": "color",
"visibleIf": {
"all": [
{"field": "visible_parts", "includes": "min_max"},
{"not": {"field": "use_metric_colors"}}
]
}
}
Hide a Whole Group
Hide a fieldset with all its fields until a metric is selected, and a tab while the widget is set to compact:
{
"layout": [
"metric",
{
"type": "fieldset",
"label": "Value",
"visibleIf": {"field": "metric", "set": true},
"children": ["precision", "unit"]
},
{
"type": "tabs",
"children": [
{"type": "tab", "label": "General", "children": ["compact", "font"]},
{
"type": "tab",
"label": "Details",
"hideIf": {"field": "compact"},
"children": ["show_history", "history_length"]
}
]
}
]
}
Within a Repeater
Fields of a repeater item can depend on the fields of the same item and on the fields of the widget:
{
"config": [
{
"name": "show_labels",
"label": "Show labels",
"type": "checkbox",
"defaultValue": true
},
{
"name": "bars",
"label": "Bars",
"type": "repeater",
"config": [
{"name": "metric", "label": "Metric", "type": "metric"},
{
"name": "label",
"label": "Label",
"type": "string",
"visibleIf": {"field": "show_labels"}
},
{"name": "custom_color", "label": "Custom color", "type": "checkbox"},
{
"name": "color",
"label": "Color",
"type": "color",
"visibleIf": {"field": "custom_color"}
}
]
}
]
}
label checks show_labels of the widget, color checks custom_color of its own repeater item.