Light control

Who it’s for

Dashboard authors who need one light on one card ask “how do I give someone a switch, a brightness slider and a color picker for a single light, without wiring three separate widgets together?” This card answers that directly: one card, one device, and any of the three controls can be turned off if the light doesn’t have that capability.

What it does

Out of the box the card is a full light control: a switch, a 0–100% brightness slider and a color picker, sending RPC commands setBrightness, setState and setColor. Hide any of the three for a plain dimmer, a plain switch, or a switch-and-color card with no slider.

• Switch, slider and color, each independently hideable — a card can be as simple or as complete as the light needs
• One command per gesture — dragging the slider across many levels sends the level you settle on, not every level crossed on the way
• Always reads the light’s actual state, even when writes go out as RPC commands — level, on/off state and color come from the device’s attributes on load and on every poll, regardless of how changes are sent
• The slider locks while the light is off, so a level can’t be set on a dark lamp
• Optional queueing for an offline device, with retries, when writes go out as RPC
• Accent color follows the ThingsBoard theme unless you override it
• Writes either one-way RPC commands or device attributes; it does not wait for a device reply, so what actually happened is best confirmed with a feedback key elsewhere or a separate alarm

How to set up

Data keys

This is a control widget: it takes no data keys. Choose a Target device in the widget configuration — everything the card reads and writes goes to that one device, so add one card per light.

Reading always goes through the three attributes above, no matter what What a change does is set to — so even in RPC mode, keep those attributes updated on the device for the card to show the light’s real state on load and on every poll. Writing follows What a change does: RPC commands, or the same attributes.

What the device receives picks the parameter shape for all three RPC commands: an object like {"value": 60} with a parameter name you set, the number alone, or a custom Payload function(value). The function receives one argument, value — the level as a number, the switch as a boolean, the color as a string or object; its type tells you which command is being built:

if (typeof value === 'boolean') { return { on: value }; }
if (typeof value === 'string')  { return { rgb: value }; }
return { level: value, fade: 500 };

If the function returns nothing or throws, the change counts as failed: nothing is sent, and the device name turns red until a later change succeeds. A function that will not compile is caught when the card loads rather than on first use.

A one-way command nobody answers is not an error, so a device with no matching RPC handler will appear to accept changes and do nothing. If your lights work through shared attributes, switch What a change does over.

Delivery

Range

Color

How to customize

Visibility & layout

• To hide the switch — turn off Show the ‘On/off’ switch; the state attribute is still read, just not shown or switchable here.
• To hide the slider for a switch-and-color card — turn off Show the level slider.
• To move the color control below the slider instead of the top row — set Color control position; worth it once the presets are shown and there are several.
• To show the value in a floating bubble while dragging — turn on Show the value in a bubble while dragging; it needs room beside the slider and is drawn outside the widget on a small card, which is why it’s off by default.
• To show the level as text next to the slider — turn on Display current value; edit Brigtness unit to change or remove the %.

Color picker

• To offer only a fixed list of colors instead of the full picker — turn off Allow any color.
• To change that fixed list — edit Preset colors; comma-separated, hex, #RGB, "r,g,b" and rgb(r,g,b) are all accepted.
• To change the color shown before the device has reported one — set Default color.

Labels & fonts

• To change the name shown on the card — edit Name shown on the card; empty uses the device’s label, then its name.
• To match your dashboard’s fonts — set Label font and, when Display current value is on, Current value font.
• To recolor the name, the accent, or a failed-change indicator — set Label color, Accent — switch and slider, and Error color (the name stays this color until a change succeeds).

The card draws no title of its own — only the device name. The widget’s own Appearance tab still controls the title, background, padding and drop shadow; the title and the shadow ship off by default for this widget.

What the card shows while a change is in flight

The switch, slider and swatch move to the value you chose as soon as the gesture settles, not once the device confirms — so the card can be ahead of the light for as long as the request takes. A failed change is reported and turns the device name red rather than being dropped silently.

If the device has never reported its on/off state, the switch starts on and the slider stays usable. Treating an unknown state as off would lock a card that may be perfectly healthy.

Tips

• Keep every attribute the light actually reports up to date, even in RPC mode — reading always goes through the three attributes, so a light that only answers RPC and never updates its attributes shows a card that’s permanently out of sync.
• A device that’s often offline is a better fit for Write an attribute than RPC — the attribute waits for it, and nothing has to be queued.
• The Timeout (ms) field under Command is the drag-settle delay, not a request timeout — that’s the separate Request timeout (ms) setting above it.
• Two color swatches and no slider makes a simple two-color night-light control: hide the slider and turn off Allow any color.