Skip to main content
Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use web components, native UI elements with built-in accessibility, better performance, and consistent styling with Shopify's design system. Check out the migration guide to upgrade your extension.

Switch

Use the Switch component to represent an on or off state that takes effect immediately when tapped.

Support
Targets (50)

Supported targets

Anchor to SwitchPropsSwitchProps

Anchor to accessibilityLabel
accessibilityLabel
string

A label used for users of assistive technologies.

Anchor to checked
checked
boolean

Whether the switch is active.

Anchor to disabled
disabled
boolean

Whether the switch is disabled, preventing any user interaction.

Anchor to id
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.

Anchor to label
label
string

The text displayed as the switch label, which identifies the purpose of the switch to users.

Anchor to name
name
string

An identifier for the field that is unique within the nearest containing Form component.

Anchor to onChange
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, so you must store this value in state and reflect it back in the checked or value props.

Anchor to toggles
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.

Anchor to value
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.

Anchor to ExamplesExamples

Anchor to Basic SwitchBasic Switch

Basic Switch

Example

Basic Switch

import {
reactExtension,
Switch,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
'purchase.checkout.block.render',
() => <Extension />,
);

function Extension() {
return (
<Switch accessibilityLabel="my-switch" />
);
}
import {extension, Switch} from '@shopify/ui-extensions/checkout';

export default extension('purchase.checkout.block.render', (root) => {
const baseSwitch = root.createComponent(Switch, {
accessibilityLabel: 'my-switch',
});

root.appendChild(baseSwitch);
});

Anchor to Custom labelCustom label

This example demonstrates pairing the Switch component with a custom label and layout while keeping it accessible to screen readers.

Custom label

This example demonstrates pairing the Switch component with a custom label and layout while keeping it accessible to screen readers.

Custom label

import {
reactExtension,
InlineLayout,
Switch,
Text,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
'purchase.checkout.footer.render-after',
() => <Extension />,
);

function Extension() {
const switchLabel = 'Shipping insurance';
return (
<InlineLayout
padding="base"
borderRadius="base"
border="base"
columns={['fill', 'auto']}
>
<Text>{switchLabel}</Text>
<Switch accessibilityLabel={switchLabel} />
</InlineLayout>
);
}
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);
},
);

Anchor to Best practicesBest practices

  • Use for immediate effects: Reserve the Switch component for settings that take effect immediately without a save or submit action.
  • Write clear labels: Describe the setting being toggled, such as "Shipping insurance" rather than "Toggle" or "On/Off."
  • Use checkbox for deferred actions: If the setting requires form submission to apply, use the Checkbox component instead.
  • Pre-enable thoughtfully: Only use default checked state for options that benefit the buyer by default.

Anchor to LimitationsLimitations

  • The Switch component doesn't support error or required properties. For toggles that need validation, use the Checkbox component instead.

Anchor to RelatedRelated

ComponentCheckbox
Was this page helpful?