--- title: Switch description: >- The switch component provides a clear way for users to toggle options or settings on and off. Use switch for binary controls that take effect immediately, like enabling features, activating settings, or controlling visibility. Switches provide instant visual feedback and are ideal for settings that don't require a save action to apply changes. For selections that require explicit submission, use [checkbox](/docs/api/app-home//web-components/forms/checkbox) instead. api_name: app-home source_url: html: 'https://shopify.dev/docs/api/app-home/web-components/forms/switch' md: 'https://shopify.dev/docs/api/app-home/web-components/forms/switch.md' --- # Switch The switch component provides a clear way for users to toggle options or settings on and off. Use switch for binary controls that take effect immediately, like enabling features, activating settings, or controlling visibility. Switches provide instant visual feedback and are ideal for settings that don't require a save action to apply changes. For selections that require explicit submission, use [checkbox](https://shopify.dev/docs/api/app-home/web-components/forms/checkbox) instead. #### Use cases * **Binary settings:** Toggle binary settings like enable/disable or on/off states. * **Feature flags:** Control feature availability with clear on/off indicators. * **Quick toggles:** Provide quick toggle controls for frequently changed settings. * **Status changes:** Toggle resource states like active/inactive or published/unpublished. ## Properties Configure the following properties on the switch component. * **accessibilityLabel** **string** A label that describes the purpose or content of the component for assistive technologies like screen readers. Use this to provide additional context when the visible content alone doesn't clearly convey the component's purpose. * **checked** **boolean** **Default: false** Whether the control is currently checked. Use this for controlled components where you manage the checked state. * **defaultChecked** **boolean** **Default: false** The initial checked state for uncontrolled components. Use this when you want the control to start checked but don't need to control its state afterward. * **details** **string** Supplementary text displayed below the checkbox to provide additional context, instructions, or help. Use this to explain what checking the box means or provide guidance to users. This text is announced to screen readers. * **disabled** **boolean** **Default: false** Whether the field is disabled, preventing any user interaction. * **error** **string** An error message displayed below the checkbox to indicate validation problems. When set, the checkbox is styled with error indicators and the message is announced to screen readers. * **id** **string** A unique identifier for the element. Use this to reference the element in JavaScript, link labels to form controls, or target specific elements for styling or scripting. * **label** **string** The text label displayed next to the checkbox that describes what the checkbox controls. Clicking the label will also toggle the checkbox state. * **labelAccessibilityVisibility** **"visible" | "exclusive"** **Default: 'visible'** Controls whether the label is visible to all users or only to screen readers. * `visible`: The label is shown to everyone (default). * `exclusive`: The label is visually hidden but still announced by screen readers. Use `exclusive` when the surrounding context makes the label redundant visually, but screen reader users still need it for clarity. * **name** **string** The name attribute for the field, used to identify the field's value when the form is submitted. Must be unique within the nearest containing form. * **required** **boolean** **Default: false** Whether the field needs a value. This requirement adds semantic value to the field, but it will not cause an error to appear automatically. If you want to present an error when this field is empty, you can do so with the `error` property. * **value** **string** The value used in form data when the checkbox is checked. ## Events The switch component provides event callbacks for handling user interactions. Learn more about [handling events](https://shopify.dev/docs/api/app-ui/using-web-components#handling-events). * **change** **CallbackEventListener<'input'>** A callback fired when the switch value changes. Learn more about the [change event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event). * **input** **CallbackEventListener<'input'>** A callback fired when the user inputs data into the switch. Learn more about the [input event](https://developer.mozilla.org/en-US/docs/Web/API/Element/input_event). ### CallbackEventListener A function that handles events from UI components. This type represents an event listener callback that receives a \`CallbackEvent\` with a strongly-typed \`currentTarget\`. Use this for component event handlers like \`click\`, \`focus\`, \`blur\`, and other DOM events. ```ts (EventListener & { (event: CallbackEvent): void; }) | null ``` ### CallbackEvent An event object with a strongly-typed \`currentTarget\` property that references the specific HTML element that triggered the event. This type extends the standard DOM \`Event\` interface and ensures type safety when accessing the element that fired the event. ```ts Event & { currentTarget: HTMLElementTagNameMap[T]; } ``` Examples ### Examples * #### Toggle a setting ##### Description Give users a clear way to turn a feature on or off. This example pairs a label with a toggle switch. ##### html ```html ``` * #### Show a disabled switch ##### Description Indicate when a feature isn't available. This example locks a switch to prevent interaction while displaying its current state. ##### html ```html ``` * #### Submit multiple settings in a form ##### Description Collect multiple settings that save together. This example groups switches in a form for batch submission. ##### html ```html
Save preferences
``` * #### Apply multiple settings immediately ##### Description Organize settings in a panel layout. This example arranges switches in a stack to display related preferences together. ##### html ```html ``` * #### Hide the label visually ##### Description Keep switches accessible when labels aren't visually needed. This example uses a visually hidden label that screen readers can still announce. ##### html ```html ``` * #### Show validation errors ##### Description Communicate switch-related problems clearly. This example displays helper text with an error message when a required switch isn't enabled. ##### html ```html ``` * #### Add an accessibility label ##### Description Provide extra context for screen reader users. This example adds an accessibility label that gives more detail than the visible label alone. ##### html ```html ``` ## Best practices * **Don't combine with save buttons:** Switches apply changes instantly when toggled, so combining them with save buttons creates confusion about when changes take effect. * **Make the controlled setting clear:** Merchants should immediately understand what setting the switch controls and what each state means. Ambiguous labels force merchants to toggle the switch just to figure out what it does. * **Explain the impact:** Merchants need to understand the consequences of toggling a switch, especially for settings that affect important functionality or data. Without context, merchants might hesitate to change settings or make uninformed decisions. * **Organize related settings thoughtfully:** When presenting multiple switches, group related settings together and order them logically. A well-organized settings interface helps merchants find and configure options efficiently. * **Make unavailable options understandable:** When a switch is disabled due to permissions, dependencies, or plan limitations, explain why. Users should know whether the limitation is temporary or permanent and what they need to do to access the setting.