> For the complete documentation index, see [llms.txt](https://design.mirakl.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://design.mirakl.com/~/changes/DpgERwSwrKIthStzL4D6/components/actions/switch-button.md).

# Switch Button

A button that has two mutually-exclusive states with auto-save behavior.

<figure><img src="https://1297765105-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMoZPkWOmnKvoMWGW4aeM%2Fuploads%2FFzKWZdficf4rYC9j4A0Y%2FSwitch%20Button%20Hero.png?alt=media&amp;token=b4b53e3e-3971-45e8-bad5-7ee1960866ea" alt=""><figcaption></figcaption></figure>

&#x20;

## Overview <a href="#id-40e356" id="id-40e356"></a>

Also known as "Toggle", `Switch Button` allows users to switch between two mutually-exclusive states, such as:

* On/Off
* Show/Hide
* Activate/Deactivate

{% hint style="info" %}
💡 Note that usually `Switch Button` is considered a [selection control component](/~/changes/DpgERwSwrKIthStzL4D6/components/form/selection-controls.md). However, we have decided to consider it a `Button` because it has an `Auto-Save` behavior, unlike other listed components in forms. Selection Control components must follow [Form Save behavior](/~/changes/DpgERwSwrKIthStzL4D6/patterns/forms.md)
{% endhint %}

We mainly use `Switch Button` to swap between two views (Show/Hide elements). But it can also be used for use cases such as setting enablement (Activate/Deactivate).

Because **its state cannot be indeterminate,**`Switch Button` always has a **default value**. It is up to product teams to determine which one would be the best one depending on features.

This component can be used with or without a `Label`. The `Label` can be placed on the right or the left of the switch. Note that adding a `Label` is relevant to explain to users the concrete consequences of their actions.

{% hint style="danger" %}
Do not change Switch label depending on its state. The label must be understandable in both states.
{% endhint %}

If `Label` seems too short to explain the action's consequences, a`Helptext` prop can be added. Then, formatting is automated for the label to appear on the left and the switch component on the right.

<figure><img src="https://1297765105-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMoZPkWOmnKvoMWGW4aeM%2Fuploads%2FU1KRG1CG4X7AA35wkp0u%2Fimage.png?alt=media&amp;token=a4c765f3-4f1b-4470-ab3b-3b928c0f805c" alt=""><figcaption></figcaption></figure>

If disabled, a `tooltip` appearing while hovering the component can be added to explain why the action is unavailable.

<figure><img src="https://1297765105-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMoZPkWOmnKvoMWGW4aeM%2Fuploads%2F7mpamDdE18woRPQ7E2pR%2Fimage.png?alt=media&amp;token=e14c8075-6cd8-4b37-bd32-1383a22a2ce1" alt=""><figcaption></figcaption></figure>

[`Switch Button` has a generic autosave behavior, but you may add a confirmation modal to make sure users understand what they're activating.](#user-content-fn-1)[^1]

## Key takeaways <a href="#id-8864e6" id="id-8864e6"></a>

{% hint style="success" %}

* Add a short label to help users understand the consequence of the action.
* Think wisely about the Default state.
* Add a tooltip to a disabled state to explain why the action is unavailable.
  {% endhint %}

{% hint style="danger" %}

* Add a Save pattern to Switch Button; their action is immediate and does not need confirmation from the user.
* Change label depending on the state; Label must remain the same.
  {% endhint %}

[^1]: [Romain Séchan](mailto:undefined) ?


---

# 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://design.mirakl.com/~/changes/DpgERwSwrKIthStzL4D6/components/actions/switch-button.md?ask=<question>&goal=<endgoal>
```

`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.