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.

Choose a version:

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

Support

Targets (25)

Supported targets

Anchor to PropertiesProperties

Configure the following properties on the Switch component.

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 Toggle a settingToggle 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

A switch toggle in the off position with a label

Toggle a setting

import {

reactExtension,

Switch,

} from '@shopify/ui-extensions-react/customer-account';

export default reactExtension(

'customer-account.page.render',

() => <Extension />,

);

function Extension() {

return (

);

}

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);

});

React

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

export default reactExtension(
  'customer-account.page.render',
  () => <Extension />,
);

function Extension() {
  return (
    <Switch accessibilityLabel="my-switch" />
  );
}

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);
});

Anchor to Pair with a custom labelPair 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

A switch toggle paired with a custom label layout

Pair with a 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>

</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);

);

React

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>
  );
}

JavaScript

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 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 instead.
Pre-enable thoughtfully: Only use defaultChecked for options that benefit the customer by default.

Anchor to LimitationsLimitations

No error or required props available.

Was this page helpful?