ModifierGroup

Install and import

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

Guidelines

A group of options for a dish, such as "Choose a size" or "Add extras": radios for one choice or checkboxes for several, in full-width rows with the price change on the right.

Use it when

• A dish has options that change what is made or what it costs, usually in a Sheet opened from a MenuItem.
• One choice is required (a size) or several are allowed up to a limit (extras).

Don't use it when

• It is a form field that is not about a product's options. Use RadioGroup or CheckboxGroup.
• The choice is a number of the same thing. Use QuantityStepper.
• There are two options without prices that switch a mode. Use FulfilmentToggle or Switch.

Example

<ModifierGroup
  title="Choose a size"
  mode="single"
  required
  options={[{ id: "regular", label: "Regular" }, { id: "large", label: "Large", price: 2 }]}
  value={size}
  onChange={setSize}
  error={tried && !size.length ? "Choose a size to continue." : undefined}
/>

<ModifierGroup
  title="Add extras"
  mode="multiple"
  max={3}
  options={[
    { id: "egg", label: "Fried egg", price: 2 },
    { id: "tofu", label: "Extra tofu", price: 1.5 },
    { id: "chicken", label: "Chicken", price: 2.5, disabled: true, note: "Sold out today" },
  ]}
  value={extras}
  onChange={setExtras}
/>

Variants

Composition

Usually two or three groups stacked in a Sheet, with a footer Button that adds the dish and shows the running total: "Add to basket · $14.50". The price deltas render with Price. Controlled: the choices and the total live in your app.

Tokens

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

• Rows: --dt-modifier-row-min-height (--dt-size-touch-target), --dt-modifier-divider (--dt-border-subtle).
• The drawn control: --dt-modifier-control-size (--dt-size-icon-md), --dt-modifier-control-border (--dt-border-strong), --dt-modifier-control-bg (--dt-input-bg), --dt-modifier-control-accent (--dt-surface-action), --dt-modifier-control-mark (--dt-text-on-action).
• --dt-modifier-delta-color and --dt-modifier-hint-color (--dt-text-secondary).
• The pill and error: --dt-modifier-pill-bg (--dt-surface-sunken), --dt-modifier-pill-fg (--dt-text-secondary), --dt-modifier-error-color (--dt-text-danger), --dt-modifier-error-pill-bg (--dt-surface-danger-subtle).

The title is --dt-text-heading-xs-*; option labels --dt-text-body-md-*. A disabled option reads --dt-text-disabled, --dt-border-disabled and --dt-surface-disabled.

Accessibility

• A <fieldset> whose <legend> holds the title and the Required pill, so the group's name is "Choose a size Required".
• The controls are native radio and checkbox inputs, laid transparently over the drawn ones, so the keyboard works as it does everywhere: in single mode Tab reaches the group once and the arrow keys move and choose; in multiple mode each checkbox is a tab stop and Space toggles it. The focus ring is drawn on the visible control.
• Single mode sets role="radiogroup" on the fieldset, with aria-required and aria-invalid when they apply. The hint and the error are linked to the group with aria-describedby; the error is also a role="alert", so it is announced when it appears. In multiple mode each checkbox is aria-invalid while there is an error.
• The price delta and the note are inside each option's label, so they are part of its name: "Large +$2.00".
• An option disabled because the limit is reached says so in its name, so a screen reader user knows why they can't choose it.
• Every row is at least a touch target tall and the whole row is the label.

Content

• The title is a short instruction or a noun: "Choose a size", "Add extras", "Spice level".
• Option labels are nouns, sentence case: "Large", "Fried egg".
• The error says what to do: "Choose a size to continue."
• Notes are a few words: "Contains peanuts", "Sold out today".

Props

The typed contract, from ModifierGroup.d.ts.

import * as React from "react";

/** One choice in a modifier group. */
export interface ModifierOption {
  /** Unique within the group. This is what value holds. */
  id: string;
  /** The choice's name: "Large", "Extra egg". */
  label: string;
  /** Price change in major units, shown as "+$1.50". 0 or undefined shows nothing; a negative shows "−$1.00". */
  price?: number;
  /** Greys the choice out and removes it from the tab order. Say why in note. */
  disabled?: boolean;
  /** A short line under the label: "Contains peanuts", "Sold out today". */
  note?: string;
}

/** A group of options for a dish, such as "Choose a size" or "Add extras": radios or checkboxes in full-width rows. */
export interface ModifierGroupProps extends Omit<React.HTMLAttributes<HTMLFieldSetElement>, "onChange" | "title" | "children" | "defaultValue"> {
  /** The group's name, rendered as the fieldset's legend. */
  title: string;
  /** The choices, in order. */
  options: ModifierOption[];
  /** single: radios, one choice. multiple: checkboxes. */
  mode: "single" | "multiple";
  /** The chosen ids. Single mode uses one element (or none). Controlled. */
  value: string[];
  /** Called with the next list of chosen ids. */
  onChange: (next: string[]) => void;
  /** Shows the Required pill, and marks a single-choice group aria-required. */
  required?: boolean;
  /** Multiple mode: the fewest choices, stated in the hint. The group does not enforce it; set error when it is not met. */
  min?: number;
  /** Multiple mode: the most choices. Once reached, the other options disable, and each says why in its accessible name. */
  max?: number;
  /** An error under the title, announced when it appears and linked to the group with aria-describedby. It turns the Required pill red. */
  error?: string;
  /** Replaces the generated hint ("Choose up to 3", "Choose 1 to 3"). */
  hint?: string;
  /** ISO 4217 currency code for the price deltas. @default "USD" */
  currency?: string;
  /** BCP 47 locale for the price deltas. Defaults to the runtime's. */
  locale?: string;
  /** Text of the Required pill. @default "Required" */
  requiredLabel?: string;
  /** Added, visually hidden, to the name of an option disabled by max. @default (max) => `, limit of ${max} reached` */
  limitLabel?: (max: number) => string;
}

export declare function ModifierGroup(props: ModifierGroupProps): React.JSX.Element;

Tokens it reads

Every custom property ModifierGroup.jsx resolves, read from the source: 14 component, 164 semantic. 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.

Source

React only, no dependencies, every value a token.

import React from "react";
import { VisuallyHidden } from "../primitives/VisuallyHidden.jsx";
import { Price } from "./Price.jsx";

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

/* The rule for a multiple-choice group, in words: "Choose up to 3". */
function ruleFor(mode, min, max) {
  if (mode !== "multiple") return null;
  const hasMin = typeof min === "number" && min > 0;
  const hasMax = typeof max === "number";
  if (hasMin && hasMax) return min === max ? `Choose ${max}` : `Choose ${min} to ${max}`;
  if (hasMax) return `Choose up to ${max}`;
  if (hasMin) return `Choose at least ${min}`;
  return null;
}

const defaultLimitLabel = (max) => `, limit of ${max} reached`;

/* The drawn control. The real input sits over it, transparent, so the
   browser keeps the keyboard behaviour and the label click. */
function Mark({ single, on, off, focused }) {
  const size = "var(--dt-modifier-control-size)";
  return (
    <span
      aria-hidden="true"
      style={{
        display: "flex", alignItems: "center", justifyContent: "center",
        boxSizing: "border-box", width: size, height: size,
        borderRadius: single ? "var(--dt-radius-pill)" : "calc(var(--dt-radius-control) / 2)",
        border: single && on
          ? `calc(${size} * 0.3) solid ${off ? "var(--dt-border-disabled)" : "var(--dt-modifier-control-accent)"}`
          : `var(--dt-border-width-strong) solid ${off ? "var(--dt-border-disabled)" : on ? "var(--dt-modifier-control-accent)" : "var(--dt-modifier-control-border)"}`,
        background: off
          ? "var(--dt-surface-disabled)"
          : !single && on ? "var(--dt-modifier-control-accent)" : "var(--dt-modifier-control-bg)",
        color: "var(--dt-modifier-control-mark)",
        outline: focused ? "var(--dt-focus-ring-width) solid var(--dt-focus-ring-color)" : "none",
        outlineOffset: "var(--dt-focus-ring-offset)",
        transition: "background var(--dt-motion-micro), border var(--dt-motion-micro)",
      }}
    >
      {!single && on && (
        <svg
          viewBox="0 0 24 24" focusable="false" fill="none" stroke="currentColor" strokeWidth="3.5" strokeLinecap="round" strokeLinejoin="round"
          style={{ display: "block", width: "var(--dt-size-icon-xs)", height: "var(--dt-size-icon-xs)" }}
        >
          <path d="M20 6 9 17l-5-5" />
        </svg>
      )}
    </span>
  );
}

export function ModifierGroup({
  title,
  options = [],
  mode = "single",
  value = [],
  onChange,
  required = false,
  min,
  max,
  error,
  hint,
  currency = "USD",
  locale,
  requiredLabel = "Required",
  limitLabel = defaultLimitLabel,
  style,
  ...rest
}) {
  const uid = React.useId();
  const name = `${uid}-choice`;
  const hintId = `${uid}-hint`;
  const errorId = `${uid}-error`;
  const [focused, setFocused] = React.useState(null);
  const single = mode !== "multiple";
  const chosen = Array.isArray(value) ? value : [];
  const atMax = !single && typeof max === "number" && chosen.length >= max;
  const rule = hint || ruleFor(mode, min, max);
  const describedBy = [rule && hintId, error && errorId].filter(Boolean).join(" ") || undefined;

  const pick = (id) => {
    if (!onChange) return;
    if (single) {
      if (chosen[0] !== id || chosen.length !== 1) onChange([id]);
      return;
    }
    if (chosen.includes(id)) onChange(chosen.filter((v) => v !== id));
    else if (!atMax) onChange([...chosen, id]);
  };

  const onFocus = (e, id) => {
    let visible = true;
    try { visible = e.currentTarget.matches(":focus-visible"); } catch (err) { visible = true; }
    setFocused(visible ? id : null);
  };

  return (
    <fieldset
      role={single ? "radiogroup" : undefined}
      aria-required={single && required ? true : undefined}
      aria-invalid={single && error ? true : undefined}
      aria-describedby={describedBy}
      style={{ border: 0, margin: 0, padding: 0, minWidth: 0, display: "flex", flexDirection: "column", ...style }}
      {...rest}
    >
      <legend style={{ padding: 0, width: "100%", float: "left" }}>
        <span style={{ display: "flex", alignItems: "center", justifyContent: "space-between", gap: "var(--dt-space-inline-sm)" }}>
          <span style={{ ...role("heading-xs"), color: "var(--dt-text-primary)", minWidth: 0, overflowWrap: "anywhere" }}>{title}</span>
          {required && (
            <span
              style={{
                ...role("label-sm"), flex: "none", whiteSpace: "nowrap",
                padding: "0 var(--dt-space-inset-xs)", borderRadius: "var(--dt-radius-pill)",
                background: error ? "var(--dt-modifier-error-pill-bg)" : "var(--dt-modifier-pill-bg)",
                color: error ? "var(--dt-modifier-error-color)" : "var(--dt-modifier-pill-fg)",
              }}
            >
              {requiredLabel}
            </span>
          )}
        </span>
      </legend>
      {/* The float above takes the legend out of the fieldset's border
          layout, so it lays out like any other block; this clears it. */}
      <span aria-hidden="true" style={{ display: "block", clear: "both" }} />
      {rule && (
        <p id={hintId} style={{ ...role("body-sm"), margin: "var(--dt-space-stack-2xs) 0 0", color: "var(--dt-modifier-hint-color)" }}>{rule}</p>
      )}
      {error && (
        <p id={errorId} role="alert" style={{ ...role("body-sm"), margin: "var(--dt-space-stack-2xs) 0 0", color: "var(--dt-modifier-error-color)" }}>{error}</p>
      )}
      <div style={{ display: "flex", flexDirection: "column", marginTop: "var(--dt-space-stack-2xs)" }}>
        {options.map((opt, i) => {
          const on = single ? chosen[0] === opt.id : chosen.includes(opt.id);
          const limited = !single && atMax && !on && !opt.disabled;
          const off = !!opt.disabled || limited;
          const delta = typeof opt.price === "number" && opt.price !== 0 ? opt.price : null;
          const inputId = `${uid}-${i}`;
          return (
            <label
              key={opt.id}
              htmlFor={inputId}
              style={{
                display: "flex", alignItems: "center", gap: "var(--dt-space-inline-sm)",
                minHeight: "var(--dt-modifier-row-min-height)", boxSizing: "border-box",
                padding: "var(--dt-space-inset-xs) 0",
                borderTop: i > 0 ? "var(--dt-border-width-default) solid var(--dt-modifier-divider)" : undefined,
                cursor: off ? "not-allowed" : "pointer",
                color: off ? "var(--dt-text-disabled)" : "var(--dt-text-primary)",
              }}
            >
              <span style={{ position: "relative", flex: "none", display: "flex" }}>
                <input
                  id={inputId}
                  type={single ? "radio" : "checkbox"}
                  name={name}
                  value={opt.id}
                  checked={on}
                  disabled={off}
                  aria-invalid={!single && error ? true : undefined}
                  onChange={() => pick(opt.id)}
                  onFocus={(e) => onFocus(e, opt.id)}
                  onBlur={() => setFocused(null)}
                  style={{ position: "absolute", inset: 0, width: "100%", height: "100%", margin: 0, opacity: 0, cursor: "inherit" }}
                />
                <Mark single={single} on={on} off={off} focused={focused === opt.id} />
              </span>
              <span style={{ flex: "1 1 auto", minWidth: 0, display: "flex", flexDirection: "column" }}>
                <span style={{ ...role("body-md"), overflowWrap: "anywhere" }}>
                  {opt.label}
                  {limited && <VisuallyHidden>{limitLabel(max)}</VisuallyHidden>}
                </span>
                {opt.note && (
                  <span style={{ ...role("body-xs"), color: off ? "var(--dt-text-disabled)" : "var(--dt-text-secondary)" }}>{opt.note}</span>
                )}
              </span>
              {delta != null && (
                <span
                  style={{
                    flex: "none", display: "inline-flex", alignItems: "baseline",
                    ...role("label-md"),
                    color: off ? "var(--dt-text-disabled)" : "var(--dt-modifier-delta-color)",
                    "--dt-price-color": off ? "var(--dt-text-disabled)" : "var(--dt-modifier-delta-color)",
                  }}
                >
                  {delta > 0 ? "+" : "−"}
                  <Price amount={Math.abs(delta)} currency={currency} locale={locale} size="sm" />
                </span>
              )}
            </label>
          );
        })}
      </div>
    </fieldset>
  );
}