Skip to main content

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.

mobro-widget-config.json
{
"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:

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.

PropertyTypeDescription
visibleIfConditionOnly shows the field or layout element while the condition passes.
hideIfConditionHides 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"}}.

Hidden fields keep their values

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.

ConditionPasses 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​

CheckTypePasses if
equalsanyThe value equals this one. Objects and lists are compared by their content.
notEqualsanyThe value doesn't equal this one.
inarrayThe value equals one of these.
notInarrayThe value equals none of these.
setbooleantrue: the field has a value. false: it has none. See Set and Truthy.
truthybooleantrue: the value is truthy. false: it isn't. See Set and Truthy.
includesanyThe list contains this item, like an option picked in a multi-select. For a text: the text contains this text.
includesAnyarrayThe list contains at least one of these items.
includesAllarrayThe list contains all of these items.
gtnumberThe value is a number greater than this one.
gtenumberThe value is a number greater than or equal to this one.
ltnumberThe value is a number less than this one.
ltenumberThe 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​

Valuesettruthy
No valuefalsefalse
Empty text "", empty list [], empty object {}falsefalse
false, 0truefalse
Anything else, like true, "abc", ["a"], a metrictruetrue

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:

mobro-widget-config.json
{
"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:

mobro-widget-config.json
{
"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:

mobro-widget-config.json
{
"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.