Setting toggle

Use to give merchants control over a feature or option that can be turned on or off.


The SettingToggle is a simple layout component that composes its children with a button in a card. This pattern should be built using the primitive layout and typography components. See the "With primitive components" example to learn how to build setting toggles with primitive components.

Setting toggle component examples

Use to allow merchants to toggle a setting that has an on or off state. Display the name of the setting and provide a description so merchants have the context needed to decide whether or not to enable the setting. This pattern is built using the layout and typography components, instead of the deprecated SettingToggle component.

import {
} from '@shopify/polaris';
import {InfoIcon} from '@shopify/polaris-icons';
import {useState, useCallback} from 'react';

export function WithPrimitiveComponents() {
  const [enabled, setEnabled] = useState(true);

  const handleToggle = useCallback(() => setEnabled((enabled) => !enabled), []);

  const contentStatus = enabled ? 'Turn off' : 'Turn on';

  const toggleId = 'setting-toggle-uuid';
  const descriptionId = 'setting-toggle-description-uuid';

  const {mdDown} = useBreakpoints();

  const badgeStatus = enabled ? 'success' : undefined;

  const badgeContent = enabled ? 'On' : 'Off';

  const title = 'Test mode';
  const description =
    'Simulate transactions to test your checkout and order flows. When test mode is on, checkout does not accept real credit cards.';

  const settingStatusMarkup = (
      toneAndProgressLabelOverride={`Setting is ${badgeContent}`}

  const helpLink = (
    <Button variant="plain" icon={InfoIcon} accessibilityLabel="Learn more" />

  const settingTitle = title ? (
    <InlineStack gap="200" wrap={false}>
      <InlineStack gap="200" align="start" blockAlign="baseline">
        <label htmlFor={toggleId}>
          <Text variant="headingMd" as="h6">
        <InlineStack gap="200" align="center" blockAlign="center">
  ) : null;

  const actionMarkup = (
      ariaChecked={enabled ? 'true' : 'false'}

  const headerMarkup = (
    <Box width="100%">
        {!mdDown ? (
          <Box minWidth="fit-content">
            <InlineStack align="end">{actionMarkup}</InlineStack>
        ) : null}

  const descriptionMarkup = (
    <BlockStack gap="400">
      <Text id={descriptionId} variant="bodyMd" as="p" tone="subdued">
      {mdDown ? (
        <Box width="100%">
          <InlineStack align="start">{actionMarkup}</InlineStack>
      ) : null}

  return (
      <BlockStack gap={{xs: '400', sm: '500'}}>
        <Box width="100%">
          <BlockStack gap={{xs: '200', sm: '400'}}>
        <Text variant="bodyMd" as="p">
          Your checkout is only accepting test payments.

Best practices

Settings toggles should:

  • Include a title
  • Include body content describing the experience when the setting is turned on
  • Use a badge to clearly indicate whether the setting is turned on or off
  • Use a default button for both states. A primary button can be misinterpreted as the setting being turned on.

If more information is needed to explain setting details or functionality, include the Info icon and link to help content or related documentation.


The setting toggle component should only be used when:

  • The setting is stand alone
  • There are two binary options that are “On”/“Off”

If the setting is dependent on other settings, uses progressive disclosure, or has options that are not a simple “On”/“Off”, use a different UI element such as Checkbox or Radio button.

Content guidelines

Card title

The setting toggle title should:

  • Be the setting name, written as a noun or gerund (-ing) phrase (“Test mode” or “Automatic order archiving”)
  • Represent the experience when the setting is turned on—even if the setting restricts, limits, removes, or hides functionality
  • Test mode
  • Order archiving
  • Self-serve returns
  • Simulate test payments
  • Automatically archive the order
  • Allow customers to manage returns

On/Off button

The button for the setting toggle should always say either “Turn on” or “Turn off” depending on whether the setting can be turned on or off.

  • Turn on
  • Turn off
  • Enable
  • Disable
  • Activate
  • Deactivate

Supporting content

In addition to the setting description, supporting content can dynamically display based on state. This should be used sparingly and included only if it adds significant clarity or value. For example, “Your customers won’t receive automatic shipping updates.”

To let merchants connect or disconnect third-party services and apps, use the account connection component.


The SettingToggle component is implemented as an HTML <button> with the switch ARIA role. The components passed as children will automatically be wrapped in a label element describing the <button>. Enabling and disabling SettingToggle will update the aria-checked attribute to "true" or "false".

To learn more about button accessibility, check out the button component documentation.

    On this page