Toggle button

Who it’s for

Anyone who needs a checked-or-unchecked control that fills the space it is given — an enable flag on a settings panel, a mode selector on a compact tile, a control that has to stretch across a card rather than sit as a small switch.

What it does

The Toggle button switches between checked and unchecked, filling its tile horizontally or vertically. The state is fetched by a configured action and each transition sends its own, and the checked and unchecked appearances are configured separately rather than being two shades of one style.

• Fills its tile — horizontal or vertical fill makes the control the whole card, which suits a touch panel more than a small switch does.
• State is read back, not assumed — the initial state action fetches from an attribute, a telemetry key, an RPC call or an alarm status.
• Check and uncheck are separate actions, for devices where the two transitions differ.
• The checked and unchecked appearances are configured independently, including their own labels and icons.
• A disabled condition greys the control out, distinguishing unchecked from unavailable.
• Auto scale keeps the label proportional as the tile is resized.
• The Toggle button is a two-state control: three or more options belong on the Two-segment button or a set of command buttons.

How to set up

Data keys

The Toggle button takes no data keys — state and commands come from its configured actions.

Attribute	Scope	Operation	Description
Configured key	Any for read, Shared / Server for write	Read + Write	With Initial state set to Get attribute the button reads this key; with the check and uncheck actions set to Set attribute it writes it.

Method	Direction	Parameters	Sent when
Check method	One-way or two-way, as configured	Constant or from a convert function	When the operator checks the button
Uncheck method	One-way or two-way, as configured	Constant or from a convert function	When the operator unchecks it

Behavior

Setting	Default	Effect
Initial state	Unset	How the current state is fetched
Check	Unset	The action performed to check the component
Uncheck	Unset	The action performed to uncheck it
Disabled state	Unset	An action deciding when the button is greyed out

How to customize

• To read the real state — set Initial state to the action matching how the device reports, with a parse function if the value is not a boolean.
• To command the device — set Check and Uncheck to their own actions.
• To make the tile fill its space — turn on Horizontal fill or Vertical fill.
• To distinguish the two states — set the Checked and Unchecked button appearances separately, including their labels and icons.
• To keep text proportional — leave Auto scale on, or turn it off to pin an exact size.
• To block operation under a condition — configure the Disabled state action.
• To match the card — set the background and card padding.

Tips

• Give the checked and unchecked states different labels rather than the same word in two colors. A filled button carries enough area to say Auto mode and Manual mode, and that removes the guesswork about which state is currently active.
• Use fill mode on touch panels and leave it off on dense dashboards. A control sized for a finger is unmistakable on a wall-mounted tablet and disproportionate in a grid of small tiles.