Switch
The switch component creates a toggle control that allows merchants to turn an option on or off. Use switches for settings that take effect immediately, such as enabling notifications or toggling features.
Switches provide clear visual feedback about the current state and are ideal for binary choices that don't require confirmation.
Supported targets
- pos.
cart. line-item-details. action. render - pos.
customer-details. action. render - pos.
draft-order-details. action. render - pos.
exchange. post. action. render - pos.
home. modal. render - pos.
order-details. action. render - pos.
product-details. action. render - pos.
purchase. post. action. render - pos.
register-details. action. render - pos.
return. post. action. render
Supported targets
- pos.
cart. line-item-details. action. render - pos.
customer-details. action. render - pos.
draft-order-details. action. render - pos.
exchange. post. action. render - pos.
home. modal. render - pos.
order-details. action. render - pos.
product-details. action. render - pos.
purchase. post. action. render - pos.
register-details. action. render - pos.
return. post. action. render
Anchor to PropertiesProperties
Configure the following properties on the switch component.
- Anchor to accessibilityLabelaccessibilityLabelaccessibilityLabelstringstring
A label used for users using assistive technologies like screen readers. When set, any children or
labelsupplied will not be announced. This can also be used to display a control without a visual label, while still providing context to users using screen readers.- Anchor to checkedcheckedcheckedbooleanbooleanDefault: falseDefault: false
Whether the control is active.
- Anchor to defaultCheckeddefaultCheckeddefaultCheckedbooleanbooleanDefault: falseDefault: false
Whether the control is active by default.
- Anchor to detailsdetailsdetailsstringstring
Additional text to provide context or guidance for the field. This text is displayed along with the field and its label to offer more information or instructions to the user.
This will also be exposed to screen reader users.
- Anchor to disableddisableddisabledbooleanbooleanDefault: falseDefault: false
Disables the control, disallowing any interaction.
- Anchor to errorerrorerrorstringstring
Indicate an error to the user. The field will be given a specific stylistic treatment to communicate problems that have to be resolved immediately.
- Anchor to labellabellabelstringstring
Visual content to use as the control label.
- Anchor to labelAccessibilityVisibilitylabelAccessibilityVisibilitylabelAccessibilityVisibility'visible' | 'exclusive''visible' | 'exclusive'Default: 'visible'Default: 'visible'
Changes the visibility of the component's label.
visible: the label is visible to all users.exclusive: the label is visually hidden but remains in the accessibility tree.
- Anchor to valuevaluevaluestringstring
The value used in form data when the control is checked.
Anchor to EventsEvents
The switch component provides event callbacks for handling user interactions. Learn more about handling events.
- Anchor to changechangechange(event: CallbackEvent<"s-switch">) => void(event: CallbackEvent<"s-switch">) => void
- Anchor to inputinputinput(event: CallbackEvent<"s-switch">) => void(event: CallbackEvent<"s-switch">) => void
CallbackEvent
- bubbles
boolean - cancelable
boolean - composed
boolean - currentTarget
HTMLElementTagNameMap[T] - detail
any - eventPhase
number - target
HTMLElementTagNameMap[T] | null
Anchor to ExamplesExamples
Anchor to Create a toggle switchCreate a toggle switch
Toggle settings on or off using a switch component.Create a toggle switch
Create a toggle switch
Anchor to Handle switch change eventsHandle switch change events
Subscribe to the onChange event to respond when merchants toggle the switch. This example shows how to handle state changes and capture the checked value in real time, enabling dynamic behavior based on the switch state.Preview
Handle switch change events
Anchor to AccessibilityAccessibility
- Provide descriptive labels: Use the
labelprop to clearly describe what the switch controls. - Use accessibility labels when needed: If the visual label doesn't provide enough context, use the
accessibilityLabelprop to provide additional information for screen readers. - Indicate disabled state: When a switch is disabled, ensure the reason is communicated to users through surrounding context or helper text.