---
title: Switch
description: >-
The switch component provides a way for customers to toggle settings on and
off.
api_version: 2025-07
api_name: customer-account-ui-extensions
source_url:
html: >-
https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/forms/switch
md: >-
https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/forms/switch.md
---
Migrate to Polaris
Version 2025-07 is the last API version to support React-based UI components. Later versions use [web components](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/polaris-web-components), native UI elements with built-in accessibility, better performance, and consistent styling with [Shopify's design system](https://shopify.dev/docs/apps/design). Check out the [migration guide](https://shopify.dev/docs/apps/build/customer-accounts/migrate-to-web-components) to upgrade your extension.
# Switch
The switch component provides a clear way for customers to toggle 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. For selections that require explicit submission, use [Checkbox](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/forms/checkbox) instead.
### Support Targets (25)
### Supported targets
* CustomerAccount::KitchenSink
* [customer-account.footer.render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/footer#footer-render-after-)
* [customer-account.order-index.announcement.render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-index#order-index-targets)
* [customer-account.order-index.block.render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-index#order-index-block-)
* [customer-account.order-status.announcement.render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#order-status-announcement-)
* [customer-account.order-status.block.render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#order-status-block-)
* [customer-account.order-status.cart-line-item.render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#cart-line-item-render-after-)
* [customer-account.order-status.cart-line-list.render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#cart-line-list-render-after-)
* [customer-account.order-status.customer-information.render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#customer-information-render-after-)
* [customer-account.order-status.fulfillment-details.render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/fulfillment-status#fulfillment-status-targets)
* [customer-account.order-status.payment-details.render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/payments-and-returns#payments-and-returns-targets)
* [customer-account.order-status.return-details.render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/payments-and-returns#return-details-render-after-)
* [customer-account.order-status.unfulfilled-items.render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/fulfillment-status#unfulfilled-items-render-after-)
* [customer-account.order.action.menu-item.render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-actions#order-action-menu-item-)
* [customer-account.order.action.render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-actions#order-action-)
* [customer-account.order.page.render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/full-page#order-specific-full-page-)
* [customer-account.page.render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/full-page#customer-account-full-page-)
* [customer-account.profile.addresses.render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-default#profile-page-default-targets-)
* [customer-account.profile.announcement.render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-default#announcement-)
* [customer-account.profile.block.render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-default#profile-block-)
* [customer-account.profile.company-details.render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-b2b#profile-page-b2b-targets-)
* [customer-account.profile.company-location-addresses.render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-b2b#company-location-addresses-render-after-)
* [customer-account.profile.company-location-payment.render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-b2b#company-location-payment-render-after-)
* [customer-account.profile.company-location-staff.render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-b2b#company-location-staff-render-after-)
* customer-account.profile.payment.render-after
#### Use cases
* **Feature toggles**: Let customers enable or disable optional features instantly.
* **Notification preferences**: Allow customers to control email or SMS alerts.
* **Pre-enabled defaults**: Show a setting that's already turned on for convenience.
* **Disabled states**: Prevent toggling when a prerequisite isn't met.
***
## Properties
Configure the following properties on the Switch component.
* **accessibilityLabel**
**string**
A label used for users of assistive technologies.
* **checked**
**boolean**
Whether the switch is active.
* **disabled**
**boolean**
Whether the switch is disabled, preventing any user interaction.
* **id**
**string**
A unique identifier for the component. Use this to target the component in scripts or stylesheets, or to distinguish it from other instances of the same component.
* **label**
**string**
The text displayed as the switch label, which identifies the purpose of the switch to users.
* **name**
**string**
An identifier for the field that is unique within the nearest containing `Form` component.
* **onChange**
**(value: boolean) => void**
A callback fired when the switch value changes. This callback is called with a boolean indicating whether the switch should now be active or inactive. This component is [controlled](https://reactjs.org/docs/forms.html#controlled-components), so you must store this value in state and reflect it back in the `checked` or `value` props.
* **toggles**
**string**
The ID of the component whose visibility will be toggled when this component is activated. Use this to show or hide related content like a disclosure panel.
* **value**
**boolean**
Whether the switch is selected. This prop is an alias for `checked`, and can be useful in form libraries that provide a normalized API for dealing with both `boolean` and `string` values. If both `value` and `checked` are set, `checked` takes precedence.
***
## Examples
### Toggle a setting
Use switch to let customers turn a setting on or off with a single tap. This example shows a basic switch toggle in its default state.
## Toggle a setting
## Toggle a setting
##### React
```tsx
import {
reactExtension,
Switch,
} from '@shopify/ui-extensions-react/customer-account';
export default reactExtension(
'customer-account.page.render',
() => ,
);
function Extension() {
return (
);
}
```
##### JS
```js
import {extension, Switch} from '@shopify/ui-extensions/customer-account';
export default extension('customer-account.page.render', (root) => {
const baseSwitch = root.createComponent(Switch, {
accessibilityLabel: 'my-switch',
});
root.appendChild(baseSwitch);
});
```
### Pair with a custom label
This example demonstrates pairing the switch with a custom label and layout while keeping it accessible to screen readers.
## Pair with a custom label
## Pair with a custom label
##### React
```tsx
import {
reactExtension,
InlineLayout,
Switch,
Text,
} from '@shopify/ui-extensions-react/checkout';
export default reactExtension(
'purchase.checkout.footer.render-after',
() => ,
);
function Extension() {
const switchLabel = 'Shipping insurance';
return (
{switchLabel}
);
}
```
##### JavaScript
```js
import {
extension,
InlineLayout,
Switch,
Text,
} from '@shopify/ui-extensions/checkout';
export default extension(
'purchase.checkout.block.render',
(root) => {
const switchLabel = 'Shipping insurance';
const inlineLayout = root.createComponent(
InlineLayout,
{
padding: 'base',
borderRadius: 'base',
border: 'base',
columns: ['fill', 'auto'],
},
[
root.createComponent(
Text,
null,
switchLabel,
),
root.createComponent(Switch, {
accessibilityLabel: switchLabel,
}),
],
);
root.appendChild(inlineLayout);
},
);
```
***
## Best practices
* **Use for immediate effects**: Reserve switches for settings that take effect immediately without a save or submit action.
* **Write clear labels**: Describe the setting being toggled, such as "Order notifications" rather than "Toggle" or "On/Off."
* **Use checkbox for deferred actions**: If the setting requires form submission to apply, use [Checkbox](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/forms/checkbox) instead.
* **Pre-enable thoughtfully**: Only use `defaultChecked` for options that benefit the customer by default.
***
## Limitations
* No `error` or `required` props available.
***