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.
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 {
Text,
InlineStack,
Box,
Card,
Button,
Badge,
BlockStack,
useBreakpoints,
} 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 = (
<Badge
tone={badgeStatus}
toneAndProgressLabelOverride={`Setting is ${badgeContent}`}
>
{badgeContent}
</Badge>
);
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">
{title}
</Text>
</label>
<InlineStack gap="200" align="center" blockAlign="center">
{settingStatusMarkup}
{helpLink}
</InlineStack>
</InlineStack>
</InlineStack>
) : null;
const actionMarkup = (
<Button
role="switch"
id={toggleId}
ariaChecked={enabled ? 'true' : 'false'}
onClick={handleToggle}
size="slim"
>
{contentStatus}
</Button>
);
const headerMarkup = (
<Box width="100%">
<InlineStack
gap="1200"
align="space-between"
blockAlign="start"
wrap={false}
>
{settingTitle}
{!mdDown ? (
<Box minWidth="fit-content">
<InlineStack align="end">{actionMarkup}</InlineStack>
</Box>
) : null}
</InlineStack>
</Box>
);
const descriptionMarkup = (
<BlockStack gap="400">
<Text id={descriptionId} variant="bodyMd" as="p" tone="subdued">
{description}
</Text>
{mdDown ? (
<Box width="100%">
<InlineStack align="start">{actionMarkup}</InlineStack>
</Box>
) : null}
</BlockStack>
);
return (
<Card>
<BlockStack gap={{xs: '400', sm: '500'}}>
<Box width="100%">
<BlockStack gap={{xs: '200', sm: '400'}}>
{headerMarkup}
{descriptionMarkup}
</BlockStack>
</Box>
<Text variant="bodyMd" as="p">
Your checkout is only accepting test payments.
</Text>
</BlockStack>
</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.
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.”
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.