FulfilmentToggle

Install and import

FulfilmentToggle is in @dovetail-ds/react. Install it with React, if you haven't:

Guidelines

A segmented control for how an order reaches its buyer, delivery or pickup, with radio semantics and an optional detail line under each segment.

Use it when

• A store page or checkout lets people switch between delivery and pickup, and the page's times and fees depend on the choice.
• There are two or three ways to receive an order: add "Dine in" through options.

Don't use it when

• It switches views of content. Use Tabs.
• There are more than three choices, or the choices need descriptions. Use RadioGroup.
• It is an on/off setting. Use Switch.

Example

const [how, setHow] = React.useState("delivery");

<FulfilmentToggle
  label="How to get your order"
  value={how}
  onChange={setHow}
  options={[
    { value: "delivery", label: "Delivery", detail: "25–35 min" },
    { value: "pickup", label: "Pickup", detail: "Ready in 15" },
  ]}
/>

Variants

Composition

Sits under the StoreHeader on a store page, or at the top of a checkout. Controlled: the choice lives in your app, which changes the deliveryTime and deliveryFee it passes to StoreHeader and the totals it shows.

Tokens

Tier 3, in tokens/component/commerce.css; the colour ones are repeated under .dark:

• --dt-fulfilment-track-bg (--dt-surface-sunken), --dt-fulfilment-thumb-bg (--dt-surface-raised), --dt-fulfilment-thumb-shadow (--dt-elevation-1).
• --dt-fulfilment-fg (--dt-text-secondary), --dt-fulfilment-fg-selected (--dt-text-primary), --dt-fulfilment-detail-color (--dt-text-tertiary), --dt-fulfilment-detail-color-selected (--dt-text-secondary).
• --dt-fulfilment-inset (--dt-space-inset-2xs), --dt-fulfilment-radius (--dt-radius-container), --dt-fulfilment-thumb-radius (--dt-radius-media).

Each segment is at least --dt-size-touch-target tall. The label is --dt-text-label-md-*, semibold when chosen; the detail is --dt-text-body-xs-*. Motion is --dt-motion-micro, which is instant under reduced motion.

Accessibility

• A role="radiogroup" named by the required label; each segment is a role="radio" button with aria-checked.
• One tab stop, on the chosen segment. The arrow keys move and choose together and wrap at the ends; Home and End jump to the first and last; in a right-to-left page the horizontal arrows follow the reading direction.
• The chosen segment is marked by a raised surface and a heavier label, and announced as checked.
• The detail line is part of each segment's name: "Delivery 25–35 min".

Content

• Labels are one word, sentence case: "Delivery", "Pickup", "Dine in".
• Details are short and concrete: "25–35 min", "Ready in 15", "Free".
• The group label is a question or a noun phrase: "How to get your order".

Props

The typed contract, from FulfilmentToggle.d.ts.

import * as React from "react";

/** One way to receive the order. */
export interface FulfilmentOption {
  /** The value reported to onChange. Unique within the toggle. */
  value: string;
  /** The segment's label: "Delivery", "Pickup", "Dine in". */
  label: string;
  /** A short second line under the label: "25–35 min", "Ready in 15". */
  detail?: string;
}

/** Delivery or pickup: a segmented control with radio semantics, full width by default. */
export interface FulfilmentToggleProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChange" | "role" | "children" | "defaultValue"> {
  /** The chosen option's value. Controlled. With the default options, "delivery" or "pickup". */
  value: "delivery" | "pickup" | (string & {});
  /** Called with the newly chosen value, from a click or an arrow key. */
  onChange: (value: string) => void;
  /** The radio group's accessible name, e.g. "How to get your order". */
  label: string;
  /** The segments. @default [{ value: "delivery", label: "Delivery" }, { value: "pickup", label: "Pickup" }] */
  options?: FulfilmentOption[];
  /** Fill the container's width. false sizes it to its segments. @default true */
  fullWidth?: boolean;
  /** Disables every segment. */
  disabled?: boolean;
}

export declare function FulfilmentToggle(props: FulfilmentToggleProps): React.JSX.Element;

Tokens it reads

Every custom property FulfilmentToggle.jsx resolves, read from the source: 10 component, 154 semantic, 1 primitive. Component tier first, because that is the one to reach for.

Open the graph

• component Its own tier. Override one of these and only this component moves.
• semantic Shared roles. Override one and everything using that role moves with it.
• primitive Raw values. A component reading one directly is a deliberate exception.

Source

React only, no dependencies, every value a token.

import React from "react";

const DEFAULT_OPTIONS = [
  { value: "delivery", label: "Delivery" },
  { value: "pickup", label: "Pickup" },
];

const role = (name) => ({
  fontFamily: `var(--dt-text-${name}-family)`,
  fontSize: `var(--dt-text-${name}-size)`,
  lineHeight: `var(--dt-text-${name}-line)`,
  fontWeight: `var(--dt-text-${name}-weight)`,
  letterSpacing: `var(--dt-text-${name}-tracking)`,
});

/* A segmented control with radio semantics: one tab stop, on the chosen
   segment, and arrow keys that move and choose together, the way a native
   radio group behaves. */
export function FulfilmentToggle({
  value,
  onChange,
  label,
  options = DEFAULT_OPTIONS,
  fullWidth = true,
  disabled = false,
  style,
  ...rest
}) {
  const refs = React.useRef([]);
  const [hover, setHover] = React.useState(null);
  const index = options.findIndex((o) => o.value === value);
  const tabStop = index >= 0 ? index : 0;

  const choose = (i) => {
    const opt = options[i];
    if (!opt || disabled) return;
    if (opt.value !== value) onChange && onChange(opt.value);
    const el = refs.current[i];
    if (el) el.focus();
  };

  const onKeyDown = (e, i) => {
    const rtl = !!(e.currentTarget.closest && e.currentTarget.closest('[dir="rtl"]'));
    const fwd = rtl ? "ArrowLeft" : "ArrowRight";
    const back = rtl ? "ArrowRight" : "ArrowLeft";
    const n = options.length;
    let next = null;
    if (e.key === fwd || e.key === "ArrowDown") next = (i + 1) % n;
    else if (e.key === back || e.key === "ArrowUp") next = (i - 1 + n) % n;
    else if (e.key === "Home") next = 0;
    else if (e.key === "End") next = n - 1;
    else if (e.key === " " || e.key === "Enter") next = i;
    if (next == null) return;
    e.preventDefault();
    choose(next);
  };

  return (
    <div
      role="radiogroup"
      aria-label={label}
      aria-disabled={disabled || undefined}
      style={{
        display: fullWidth ? "grid" : "inline-grid",
        gridTemplateColumns: `repeat(${options.length}, minmax(0, 1fr))`,
        gap: "var(--dt-fulfilment-inset)",
        boxSizing: "border-box",
        width: fullWidth ? "100%" : undefined,
        padding: "var(--dt-fulfilment-inset)",
        borderRadius: "var(--dt-fulfilment-radius)",
        background: "var(--dt-fulfilment-track-bg)",
        ...style,
      }}
      {...rest}
    >
      {options.map((opt, i) => {
        const on = i === index;
        return (
          <button
            key={opt.value}
            ref={(el) => { refs.current[i] = el; }}
            type="button"
            role="radio"
            aria-checked={on}
            tabIndex={i === tabStop ? 0 : -1}
            disabled={disabled}
            onClick={() => choose(i)}
            onKeyDown={(e) => onKeyDown(e, i)}
            onMouseEnter={() => setHover(i)}
            onMouseLeave={() => setHover(null)}
            style={{
              appearance: "none", border: 0, margin: 0, minWidth: 0,
              display: "flex", flexDirection: "column", alignItems: "center", justifyContent: "center",
              gap: 0,
              minHeight: "var(--dt-size-touch-target)",
              padding: "var(--dt-space-inset-xs) var(--dt-space-inset-sm)",
              borderRadius: "var(--dt-fulfilment-thumb-radius)",
              background: on ? "var(--dt-fulfilment-thumb-bg)" : "transparent",
              boxShadow: on ? "var(--dt-fulfilment-thumb-shadow)" : "none",
              color: disabled
                ? "var(--dt-text-disabled)"
                : on || hover === i ? "var(--dt-fulfilment-fg-selected)" : "var(--dt-fulfilment-fg)",
              cursor: disabled ? "not-allowed" : "pointer",
              textAlign: "center",
              transition: "background var(--dt-motion-micro), box-shadow var(--dt-motion-micro), color var(--dt-motion-micro)",
            }}
          >
            <span style={{ ...role("label-md"), fontWeight: on ? "var(--dt-font-weight-semibold)" : "var(--dt-text-label-md-weight)",maxWidth: "100%", overflowWrap: "anywhere" }}>
              {opt.label}
            </span>
            {opt.detail && (
              <span
                style={{
                  ...role("body-xs"), maxWidth: "100%", overflowWrap: "anywhere",
                  color: disabled
                    ? "var(--dt-text-disabled)"
                    : on ? "var(--dt-fulfilment-detail-color-selected)" : "var(--dt-fulfilment-detail-color)",
                }}
              >
                {opt.detail}
              </span>
            )}
          </button>
        );
      })}
    </div>
  );
}