Setup Guide
An onboarding checklist card with a progress bar, accordion task rows and a dismiss menu, built with Polaris Card, ProgressBar, Collapsible, Popover and ActionList.
Preview
Code
Example.jsx
import { useState } from 'react';
import { ActionList, BlockStack, Box, Button, ButtonGroup, Card, Collapsible, InlineGrid, InlineStack, Popover, ProgressBar, Spinner, Text, UnstyledButton } from '@shopify/polaris';
import { ChevronDownIcon, ChevronUpIcon, ExternalSmallIcon, MenuHorizontalIcon, XSmallIcon } from '@shopify/polaris-icons';
const COLLAPSE_TRANSITION = { duration: '200ms', timingFunction: 'ease-in-out' };
const LOADING_DELAY = 1000;
const TITLE_BUTTON_STYLE = {
display: 'block',
width: '100%',
padding: 0,
border: 'none',
background: 'none',
font: 'inherit',
color: 'inherit',
textAlign: 'left',
cursor: 'pointer',
};
const TASK_ROW_STYLE = {
borderRadius: 'var(--p-border-radius-200, 0.5rem)',
padding: 'var(--p-space-200, 0.5rem)',
};
const STATUS_BUTTON_STYLE = {
appearance: 'none',
border: 'none',
background: 'none',
padding: 0,
margin: 0,
cursor: 'pointer',
display: 'flex',
lineHeight: 0,
};
const GUIDE_STYLES = `
.SetupGuide-TaskRow { transition: background-color 150ms ease; }
.SetupGuide-TaskRow:hover,
.SetupGuide-TaskRow.SetupGuide-TaskRow--selected {
background-color: var(--p-color-bg-surface-secondary, #f7f7f7);
}
.SetupGuide-StatusCircle__solid { display: none; }
.SetupGuide-StatusCircle:hover .SetupGuide-StatusCircle__dashed { display: none; }
.SetupGuide-StatusCircle:hover .SetupGuide-StatusCircle__solid { display: block; }
`;
const CircleStatusIcon = ({ completed, loading }) => {
if (loading) {
return <Spinner size="small" accessibilityLabel="Updating task status" />;
}
if (completed) {
return (
<svg width="20" height="20" viewBox="0 0 20 20" fill="none" aria-hidden="true" xmlns="http://www.w3.org/2000/svg">
<circle cx="10" cy="10" r="10" fill="var(--p-color-icon, #303030)" />
<path
fillRule="evenodd"
clipRule="evenodd"
d="M14.78 6.47a.75.75 0 0 1 0 1.06l-5.5 5.5a.75.75 0 0 1-1.06 0l-2.75-2.75a.75.75 0 1 1 1.06-1.06l2.22 2.22 4.97-4.97a.75.75 0 0 1 1.06 0Z"
fill="var(--p-color-bg-surface, #ffffff)"
/>
</svg>
);
}
return (
<svg className="SetupGuide-StatusCircle" width="20" height="20" viewBox="0 0 20 20" fill="none" aria-hidden="true" xmlns="http://www.w3.org/2000/svg">
<circle
className="SetupGuide-StatusCircle__dashed"
cx="10"
cy="10"
r="9"
fill="none"
stroke="var(--p-color-icon-secondary, #8a8a8a)"
strokeWidth="1.5"
strokeDasharray="3 3"
/>
<circle
className="SetupGuide-StatusCircle__solid"
cx="10"
cy="10"
r="9"
fill="none"
stroke="var(--p-color-icon-secondary, #8a8a8a)"
strokeWidth="1.5"
/>
</svg>
);
};
const AppEmbedIllustration = () => (
<svg width="180" height="112" viewBox="0 0 180 112" role="img" aria-label="App embed toggle in the theme editor" xmlns="http://www.w3.org/2000/svg">
<rect x="0.5" y="0.5" width="179" height="111" rx="7.5" fill="var(--p-color-bg-surface-secondary, #f7f7f7)" stroke="var(--p-color-border, #e3e3e3)" />
<rect x="12" y="14" width="80" height="8" rx="4" fill="var(--p-color-bg-fill-tertiary, #d9d9d9)" />
<rect x="12" y="36" width="156" height="28" rx="6" fill="var(--p-color-bg-surface, #ffffff)" stroke="var(--p-color-border, #e3e3e3)" />
<rect x="22" y="46" width="70" height="8" rx="4" fill="var(--p-color-bg-fill-tertiary, #d9d9d9)" />
<rect x="126" y="44" width="32" height="12" rx="6" fill="var(--p-color-bg-fill-success, #29845a)" />
<circle cx="152" cy="50" r="4" fill="#ffffff" />
<rect x="12" y="76" width="156" height="24" rx="6" fill="var(--p-color-bg-surface, #ffffff)" stroke="var(--p-color-border, #e3e3e3)" />
<rect x="22" y="84" width="54" height="8" rx="4" fill="var(--p-color-bg-fill-tertiary, #d9d9d9)" />
</svg>
);
const TASKS = [
{
id: 'enable-app-embed',
title: 'Enable the app embed in your theme',
description:
'The app embed injects the widget into your storefront. Turn it on in the theme editor, then come back and refresh the status.',
image: <AppEmbedIllustration />,
primaryAction: { content: 'Enable app embed', icon: ExternalSmallIcon },
secondaryAction: { content: 'Refresh status' },
},
{
id: 'create-first-rule',
title: 'Create your first rule',
description:
'Rules decide when the widget shows up — by product, collection, country or cart value. Start with a store-wide rule and narrow it down later.',
primaryAction: { content: 'Create rule' },
secondaryAction: { content: 'Read the guide' },
},
{
id: 'customize-widget',
title: 'Customize the widget appearance',
description:
'Match the widget to your brand: colors, corner radius, position and copy. Changes are previewed live before you save them.',
primaryAction: { content: 'Open widget settings' },
secondaryAction: { content: 'Use a preset' },
},
{
id: 'go-live',
title: 'Go live',
description:
'Publish the widget to your storefront. You can pause it at any time from the dashboard without losing your settings.',
primaryAction: { content: 'Publish to storefront' },
secondaryAction: { content: 'Preview on store' },
},
];
const TaskRow = ({ task, isSelected, isCompleted, isLoading, onToggle, onComplete, onToggleComplete }) => (
<div
className={`SetupGuide-TaskRow${isSelected ? ' SetupGuide-TaskRow--selected' : ''}`}
style={TASK_ROW_STYLE}
>
<InlineGrid columns="auto 1fr" gap="200">
<Box paddingBlockStart="050">
<UnstyledButton
accessibilityLabel={isCompleted ? 'Mark task as not done' : 'Mark task as done'}
disabled={isLoading}
onClick={onToggleComplete}
style={STATUS_BUTTON_STYLE}
>
<CircleStatusIcon completed={isCompleted} loading={isLoading} />
</UnstyledButton>
</Box>
<InlineGrid columns={isSelected && task.image ? '1fr auto' : '1fr'} gap="300">
<BlockStack gap="200">
<UnstyledButton
accessibilityLabel={task.title}
ariaExpanded={isSelected}
ariaControls={`setup-guide-task-${task.id}`}
onClick={onToggle}
style={TITLE_BUTTON_STYLE}
>
<Text as="span" fontWeight={isSelected ? 'semibold' : 'regular'}>
{task.title}
</Text>
</UnstyledButton>
<Collapsible
open={isSelected}
id={`setup-guide-task-${task.id}`}
transition={COLLAPSE_TRANSITION}
expandOnPrint
>
<BlockStack gap="300">
<Text as="p" tone="subdued">
{task.description}
</Text>
<ButtonGroup>
<Button
variant="primary"
icon={task.primaryAction.icon}
disabled={isCompleted}
loading={isLoading}
onClick={onComplete}
>
{task.primaryAction.content}
</Button>
<Button variant="plain" disabled={isLoading} onClick={onComplete}>
{task.secondaryAction.content}
</Button>
</ButtonGroup>
</BlockStack>
</Collapsible>
</BlockStack>
{isSelected && task.image ? <Box>{task.image}</Box> : null}
</InlineGrid>
</InlineGrid>
</div>
);
export const Example = () => {
const [completed, setCompleted] = useState({ 'enable-app-embed': true });
const [loading, setLoading] = useState({});
const [selected, setSelected] = useState('create-first-rule');
const [open, setOpen] = useState(true);
const [popoverActive, setPopoverActive] = useState(false);
const [dismissed, setDismissed] = useState(false);
const completedCount = TASKS.filter((task) => completed[task.id]).length;
const percentage = Math.round((completedCount / TASKS.length) * 100);
const completeTask = (id) => {
if (completed[id] || loading[id]) return;
setLoading((prev) => ({ ...prev, [id]: true }));
setTimeout(() => {
setLoading((prev) => ({ ...prev, [id]: false }));
setCompleted((prev) => ({ ...prev, [id]: true }));
}, LOADING_DELAY);
};
const toggleComplete = (id) => {
if (completed[id]) {
setCompleted((prev) => ({ ...prev, [id]: false }));
return;
}
completeTask(id);
};
const toggleTask = (id) => setSelected((prev) => (prev === id ? null : id));
if (dismissed) {
return (
<Card>
<InlineStack align="space-between" blockAlign="center">
<Text as="p" tone="subdued">
Setup guide dismissed.
</Text>
<Button variant="plain" onClick={() => setDismissed(false)}>
Show guide
</Button>
</InlineStack>
</Card>
);
}
return (
<Card padding="0">
<style>{GUIDE_STYLES}</style>
<Box padding="400">
<BlockStack gap="300">
<InlineGrid columns="1fr auto" alignItems="start">
<BlockStack gap="100">
<Text as="h2" variant="headingSm">
Setup guide
</Text>
<Text as="p" tone="subdued">
Finish these steps to start showing the widget to your customers.
</Text>
</BlockStack>
<InlineStack gap="100" blockAlign="start">
<Popover
active={popoverActive}
activator={
<Button
variant="tertiary"
icon={MenuHorizontalIcon}
accessibilityLabel="More actions"
onClick={() => setPopoverActive((prev) => !prev)}
/>
}
onClose={() => setPopoverActive(false)}
>
<ActionList
actionRole="menuitem"
items={[
{
content: 'Dismiss guide',
icon: XSmallIcon,
onAction: () => {
setPopoverActive(false);
setDismissed(true);
},
},
]}
/>
</Popover>
<Button
variant="tertiary"
icon={open ? ChevronUpIcon : ChevronDownIcon}
accessibilityLabel={open ? 'Collapse guide' : 'Expand guide'}
onClick={() => setOpen((prev) => !prev)}
/>
</InlineStack>
</InlineGrid>
<InlineGrid columns="auto 1fr" gap="300" alignItems="center">
<Text as="span" tone="subdued">
{completedCount} of {TASKS.length} tasks complete
</Text>
<ProgressBar progress={percentage} size="small" tone="primary" />
</InlineGrid>
</BlockStack>
</Box>
<Collapsible open={open} id="setup-guide-tasks" transition={COLLAPSE_TRANSITION} expandOnPrint>
<Box paddingInline="200" paddingBlockEnd="200">
<BlockStack gap="100">
{TASKS.map((task) => (
<TaskRow
key={task.id}
task={task}
isSelected={selected === task.id}
isCompleted={Boolean(completed[task.id])}
isLoading={Boolean(loading[task.id])}
onToggle={() => toggleTask(task.id)}
onComplete={() => completeTask(task.id)}
onToggleComplete={() => toggleComplete(task.id)}
/>
))}
</BlockStack>
</Box>
</Collapsible>
</Card>
);
};