> For the complete documentation index, see [llms.txt](https://docs.chirpwireless.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.chirpwireless.io/dashboards/adding-widgets/control-widget.md).
# Control Widget
Every other widget *shows* you something. The **Control widget** lets you *do* something. It puts an interactive control on your dashboard — a **switch**, **button**, **slider**, or **input** — bound to one of a device's commands, so you can operate the device without leaving the screen you're already looking at. It's the dashboard version of [Controlling Your Devices](/devices/commands.md): the command does the work, the widget is the switch on the wall.
## First, set up a command
A Control widget runs an action you've already set up on the device — so the device needs at least one command on its **Commands & States** tab. Devices with no commands won't appear to choose from (you'll see *"No controllable devices in this organization"*). Set the command up first — see [Setting up a command](/devices/commands/creating-commands.md) — then link the widget to it.
## How to add one
Every Control widget is added the same way; only the look-and-feel options differ by type.
1. Open the dashboard in **edit mode** and tap **Add widget** → **Control**.
2. On the **Datasource** tab (*"Control configuration"*), choose the **Source** (Device) and the **Device**, then pick the **Device metric** — the reading that shows the device's current state. Tap **Next**.
3. On the **Appearance** tab, give it a **Widget name** and choose a **Widget type** (below). Fill in that type's options and tap **Save**.
## Pick a control type
| Type | Great for | What it sends |
| ------------------------------------------------------------------------------- | --------------------------------------- | -------------------------------------- |
| [Switch](/dashboards/adding-widgets/control-widget/switch.md) | A simple on/off you flip back and forth | An on or off command as you toggle |
| [Button](/dashboards/adding-widgets/control-widget/button.md) | A one-tap action (run, restart, open) | One command per tap |
| [Simple Slider](/dashboards/adding-widgets/control-widget/slider-simple.md) | Sliding to a value, like brightness | A command value as you slide |
| [Circular Slider](/dashboards/adding-widgets/control-widget/slider-circular.md) | A round dial, like a knob | A command value as you turn it |
| [Vertical Slider](/dashboards/adding-widgets/control-widget/slider-vertical.md) | An upright slider you raise and lower | A command value as you slide |
| [Input](/dashboards/adding-widgets/control-widget/input.md) | Typing an exact number | A command value when you tap **Apply** |
The three sliders are the **Slider type** options — **Simple**, **Circular**, and **Vertical** — that you pick after choosing **Slider** as the widget type.
## How it behaves
* **Tap to control.** Using the control sends the command the same way the device's States tab does — same checks, same history.
* **Stays in sync.** It reads the **Device metric** and shows the real state, so it's never just guessing based on your last tap.
* **Greys out when it can't.** If the device is offline or a state isn't fully set up, the control shows as unavailable instead of sending into thin air.
## See also
* [Controlling Your Devices](/devices/commands.md) — set up the commands a Control widget uses
* [Setting up a command](/devices/commands/creating-commands.md)
* Control types: [Switch](/dashboards/adding-widgets/control-widget/switch.md) · [Button](/dashboards/adding-widgets/control-widget/button.md) · [Simple Slider](/dashboards/adding-widgets/control-widget/slider-simple.md) · [Circular Slider](/dashboards/adding-widgets/control-widget/slider-circular.md) · [Vertical Slider](/dashboards/adding-widgets/control-widget/slider-vertical.md) · [Input](/dashboards/adding-widgets/control-widget/input.md)
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.chirpwireless.io/dashboards/adding-widgets/control-widget.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.