PPolaris ComponentsConnect an agent

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