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.

Label

With help text

Label

Help text

With error text

Label

Error text

With help and error texts

Label

Help textError text

Disabled

Label

Help textError text

Label

Help textError text

Checked States

There are two checked states: checked, and not checked.

Label

Label

Label

Label

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.

TypeError: Cannot read properties of undefined (reading 'join')

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

Label

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.

Label

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

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.

What to avoid:

• 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?

Recommended settings can be active by default. When a setting is recommended, add (Recommended) to the end of its label so it can still be identified after any actions.

When should a Switch component display an error?

Never. Errors can be prevented by disabling incompatible settings automatically.

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.

What to avoid:

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

What to avoid:

• Avoid including links. Use an Alert component if this is necessary.
• Avoid writing more than one sentence.
• Avoid using periods or commas.

• What is this?
• Examples
  • Standalone
  • With help text
  • With error text
  • With help and error texts
  • Disabled
  • Checked States
  • Multiple Switches