Setting toggle
Use to give merchants control over a feature or option that can be turned on or off.
Deprecated
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.
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 {
Text,
HorizontalStack,
Box,
Card,
Button,
Badge,
VerticalStack,
useBreakpoints,
} from '@shopify/polaris';
import {CircleInformationMajor} 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 = (
<Badge
status={badgeStatus}
statusAndProgressLabelOverride={`Setting is ${badgeContent}`}
>
{badgeContent}
</Badge>
);
const helpLink = (
<Button
plain
icon={CircleInformationMajor}
accessibilityLabel="Learn more"
/>
);
const settingTitle = title ? (
<HorizontalStack gap="2" wrap={false}>
<HorizontalStack gap="2" align="start" blockAlign="baseline">
<label htmlFor={toggleId}>
<Text variant="headingMd" as="h6">
{title}
</Text>
</label>
<HorizontalStack gap="2" align="center" blockAlign="center">
{settingStatusMarkup}
{helpLink}
</HorizontalStack>
</HorizontalStack>
</HorizontalStack>
) : null;
const actionMarkup = (
<Button
role="switch"
id={toggleId}
ariaChecked={enabled ? 'true' : 'false'}
onClick={handleToggle}
size="slim"
>
{contentStatus}
</Button>
);
const headerMarkup = (
<Box width="100%">
<HorizontalStack
gap="12"
align="space-between"
blockAlign="start"
wrap={false}
>
{settingTitle}
{!mdDown ? (
<Box minWidth="fit-content">
<HorizontalStack align="end">{actionMarkup}</HorizontalStack>
</Box>
) : null}
</HorizontalStack>
</Box>
);
const descriptionMarkup = (
<VerticalStack gap="4">
<Text id={descriptionId} variant="bodyMd" as="p" color="subdued">
{description}
</Text>
{mdDown ? (
<Box width="100%">
<HorizontalStack align="start">{actionMarkup}</HorizontalStack>
</Box>
) : null}
</VerticalStack>
);
return (
<Card>
<VerticalStack gap={{xs: '4', sm: '5'}}>
<Box width="100%">
<VerticalStack gap={{xs: '2', sm: '4'}}>
{headerMarkup}
{descriptionMarkup}
</VerticalStack>
</Box>
<Text variant="bodyMd" as="p">
Your checkout is only accepting test payments.
</Text>
</VerticalStack>
</Card>
);
}
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.
Usage
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.
Do
Only include the actions Turn on/ Turn off.

Don’t
Don't include additional settings or inputs.

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
Do
- Test mode
- Order archiving
- Self-serve returns
Don’t
- 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.
Do
- Turn on
- Turn off
Don’t
- 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.”
Related components
To let merchants connect or disconnect third-party services and apps, use the account connection component.
Accessibility
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.