Switch
What is this?
Switch triggers allow merchants to instantly turn on or off the state of a feature or item.
Examples
Standalone
When using a standalone Switch you should provide an aria-label property value. As a form component, it should have a label specified to guarantee accessibility.
With help text
With error text
With help and error texts
Disabled
Checked States
There are two checked states: checked, and not checked.
Multiple Switches
It is sometimes necessary to render multiple switches and store the checked values in an array. It can be done using our useSwitchState hook. You just need to pass the hook return object to the switches state property and define a value for each Switch.
Usage
import { Switch } from '@vtex/admin-ui'
State
There are two ways of handling the state in the Switch.
checked and onChange
You can use the properties checked and onChange to handle if the Switch is checked and its values have changed."
useSwitchState
For convenience, we also provide a hook that already implements the state logic for you. It can be very handy if you have a group of switches and want to handle the states of each one. You should pass the hook return to the state property and also define a value for each Switch.
Props
| Name | Type | Description | Required | Default |
|---|---|---|---|---|
| label | ReactNode | The component's label | ✅ | - |
| helpText | ReactNode | Help text | 🚫 | - |
| errorText | ReactNode | Error text | 🚫 | - |
| error | boolean | Whether the switch contains an error or not | 🚫 | - |
| checked | boolean | Switch's checked state. If present, it is used instead of state | 🚫 | - |
| disabled | boolean | Defines if the Switch is disabled or not | 🚫 | - |
| value | string, number | Switch's value is going to be used when multiple switches share the same state. Checking a switch with a value will add it to the state array | 🚫 | - |
| state | SwtichState | Return of useSwitchState hook. You can also provide these props from your own state logic. | 🚫 | - |
| csx | StyleProp | Defines component styles | 🚫 | {} |
The Switch component also supports all HTML props from the <input /> HTML tag.
Components
When to use the Checkbox, the Button, or the Menu components instead of the Switch component?
- Choose the Checkbox component for choices that need to be saved afterwards through a form.
- Choose the Button component if the action requires confirmation or doesn’t represent an on and off semantic.
- Choose the Menu component when the feature or item has more than two states.
Position
How should a Switch component be positioned on a page?
- In left-to-right languages, a Switch component should be left-aligned.
- In a table where switching the items’ states is a common action, Switch components can be used in the last column to both display the item’s state and allow turning it on and off.
- When there are multiple Switches in a list, and they have different default states, the first sorting criteria should be their default state, from active to inactive.
- Don’t place a Switch component inside the Page Header component.
Behavior
When should a Switch be disabled?
- Use a disabled Switch only if, in some condition, it becomes enabled. For example, when the action is incompatible with an existing setting.
- Use a tooltip trigger to explain why the Switch is disabled. Display the information when hovering over the tooltip trigger — not the Switch itself.
What should be the default state of a Switch?
When should a Switch component display an error?
Content
What should be the label of a Switch?
- Start the label with a verb in the infinitive. For example, use Distribute products in marketplaces instead of Products should be distributed in marketplaces.
- Write the label so that it corresponds to the default state of the Switch.
- Use sentence case but capitalize proper nouns.
- Don't use generic verbs. For example, write Distribute products in marketplaces or Sell products from sellers instead of Enable marketplace or Enable Sellers.
- Don't leave entities implicit. For example, write Suggest pages for search engine results instead of Suggest for results.
- Don't use personal pronouns. For example, write Send to personal email instead of Send to my email.
- Don't write long labels. Use the help text to provide additional context.
- Don't write labels that vary a lot in length between options
- Don't write more than one sentence.
- Don't use periods or commas.
What should be the help text of a Switch?
- Include a help text only for critical choices where the consequences of switching the state need to be explained in more detail.
- Write the help text as if you are completing the following sentence: If you switch the default state, you or the system will [help text].
- Start with verbs in the simple present tense. For example, for the label Distribute products in marketplaces, the help text should be Sends active products to connected marketplaces and not Send active products to connected marketplaces.
- Use sentence case but capitalize proper nouns.
- Avoid including links. Use an Alert component if this is necessary.
- Avoid writing more than one sentence.
- Avoid using periods or commas.