OrderSummary

Install and import

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

Guidelines

The money breakdown of a cart or checkout: subtotal, shipping, tax and discounts as a description list, an emphasised total, an optional free-shipping progress bar, and a footer for the checkout button. It is presentational: it prints the figures it is given and adds nothing up, so your cart or your commerce platform stays the source of truth.

Use it when

• A cart page or checkout needs the totals beside the items.
• An order confirmation or receipt repeats what was charged.
• A cart drawer shows a compact subtotal with the checkout button (pass fewer lines).

Don't use it when

• You are comparing plans or prices side by side. Use Table or plan cards.
• The numbers are not money for one order (analytics, balances). Use Stat or Table.
• You need the component to calculate tax, shipping or discounts. Compute them in your app or platform and pass the results.

Example

<OrderSummary
  currency="USD"
  locale="en-US"
  lines={[
    { label: "Subtotal", amount: 138 },
    { label: "Shipping", amount: 0, hint: "Standard, 3–5 days" },
    { label: "Discount (SUMMER10)", amount: 13.8, kind: "discount" },
    { label: "Tax", amount: 9.94, kind: "muted", hint: "Estimated" },
  ]}
  total={{ amount: 134.14 }}
  freeShippingProgress={{ current: 138, threshold: 150 }}
  footer={
    <>
      <PromoCode value={code} onChange={setCode} onApply={apply} />
      <Button fullWidth size="lg">Check out</Button>
    </>
  }
/>

Variants

Composition

A panel on its own (it draws its own border and padding). It sits in the side column of a cart or checkout page, under the lines in a Drawer, or on an order confirmation. It renders Price for every figure, Progress for free shipping and Heading for its title; put PromoCode and a Button in footer.

Tokens

Tier 3, in tokens/component/commerce.css, colours repeated under .dark:

• --dt-summary-bg (--dt-surface-base), --dt-summary-border (--dt-border-subtle), --dt-summary-radius (--dt-radius-container), --dt-summary-padding (--dt-space-inset-lg): the panel.
• --dt-summary-divider (--dt-border-subtle): the rule above the total.
• --dt-summary-label-color (--dt-text-secondary), --dt-summary-value-color (--dt-text-primary): a line's label and figure.
• --dt-summary-muted-color (--dt-text-tertiary): a muted line. --dt-summary-hint-color (--dt-text-tertiary): hints.
• --dt-summary-discount-color (--dt-text-success): a discount's figure. It deliberately does not reuse --dt-price-sale-color (danger text): in a summary a discount is money saved, and red next to a promo field reads as an error. The minus sign carries the meaning, so colour is never the only signal.
• --dt-summary-total-color (--dt-text-primary): the total's label and figure.

Figures reach Price by re-pointing --dt-price-color on each figure, so a line's colour changes without changing how it is formatted. Figures are right-aligned with tabular numerals.

Accessibility

• The panel is a <section> named by its heading. The breakdown is a <dl>: each label is a <dt> and its figure a <dd>, so a screen reader pairs them, and the total is the last pair.
• A discount's figure is formatted as a negative ("-$13.80"), so it is read as money off without relying on colour.
• The free-shipping bar is a role="progressbar" named by its message, with aria-valuenow and aria-valuemax in money.
• Figures come from Intl.NumberFormat for the currency and locale; pass locale when server rendering so the server and the browser print the same.

Content

• Line labels are sentence-case nouns: "Subtotal", "Shipping", "Estimated tax". Put a discount's code in its label: "Discount (SUMMER10)".
• hint is a short fragment with no full stop: "Standard, 3–5 days", "Calculated at next step".
• Keep the total's label "Total" unless the page needs more: "Total due today", "Total (incl. VAT)".

Props

The typed contract, from OrderSummary.d.ts.

import * as React from "react";

/** One row of the money breakdown. */
export interface OrderSummaryLine {
  /** What the amount is: "Subtotal", "Shipping", "Discount (SUMMER10)". */
  label: string;
  /** Amount in major units. A discount shows as negative whatever its sign; 0 shows as "Free". */
  amount: number;
  /** discount shows the amount as a negative in the discount colour; muted is for estimates and pending figures. @default "default" */
  kind?: "default" | "discount" | "muted";
  /** A smaller line under the label: "Standard, 3–5 days", "Calculated at next step". */
  hint?: string;
}

/** The money breakdown of a cart or checkout: lines, a total, an optional free-shipping bar and a footer for actions. */
export interface OrderSummaryProps extends Omit<React.HTMLAttributes<HTMLElement>, "children" | "title"> {
  /** The rows above the total, in order. Pass what your cart computed; nothing is added up here. */
  lines: OrderSummaryLine[];
  /** The total, emphasised under a rule. */
  total: {
    /** @default "Total" */
    label?: string;
    /** Amount in major units. */
    amount: number;
  };
  /** ISO 4217 currency code. @default "USD" */
  currency?: string;
  /** BCP 47 locale. Defaults to the runtime's; set it when server rendering. */
  locale?: string;
  /** Under the total: the checkout Button, a PromoCode, trust copy. */
  footer?: React.ReactNode;
  /** Heading of the panel, also its accessible name. @default "Order summary" */
  title?: string;
  /** Level of the title's heading element. @default 2 */
  headingLevel?: 1 | 2 | 3 | 4 | 5 | 6;
  /** Shows a progress bar and "You're $12.00 away from free shipping", or "You've got free shipping" once current reaches threshold. */
  freeShippingProgress?: {
    /** The amount that counts toward the threshold, usually the subtotal. */
    current: number;
    /** The amount that unlocks free shipping. */
    threshold: number;
  };
}

export declare function OrderSummary(props: OrderSummaryProps): React.JSX.Element;

Tokens it reads

Every custom property OrderSummary.jsx resolves, read from the source: 12 component, 156 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 { Price } from "./Price.jsx";
import { Progress } from "../feedback/Progress.jsx";
import { Heading } from "../typography/Heading.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)`,
});

/* Label and figure colours per kind. A figure's colour reaches Price by
   re-pointing --dt-price-color on its wrapper, so Price keeps its own
   formatting and only the colour changes. */
const KINDS = {
  default: { label: "var(--dt-summary-label-color)", value: "var(--dt-summary-value-color)" },
  discount: { label: "var(--dt-summary-label-color)", value: "var(--dt-summary-discount-color)" },
  muted: { label: "var(--dt-summary-muted-color)", value: "var(--dt-summary-muted-color)" },
};

/* The amount in the free-shipping message, formatted the way Price formats. */
function useMoney(currency, locale) {
  return React.useMemo(() => {
    try {
      const nf = new Intl.NumberFormat(locale, { style: "currency", currency });
      return (n) => nf.format(n);
    } catch (err) {
      return (n) => `${n} ${currency}`;
    }
  }, [currency, locale]);
}

export function OrderSummary({
  lines = [],
  total,
  currency = "USD",
  locale,
  footer,
  title = "Order summary",
  headingLevel = 2,
  freeShippingProgress,
  style,
  ...rest
}) {
  const titleId = React.useId();
  const money = useMoney(currency, locale);
  const fs = freeShippingProgress;
  const reached = fs ? fs.current >= fs.threshold : false;
  const message = fs
    ? reached
      ? "You've got free shipping"
      : `You're ${money(Math.max(0, fs.threshold - fs.current))} away from free shipping`
    : null;

  const row = { display: "flex", justifyContent: "space-between", alignItems: "baseline", gap: "var(--dt-space-inline-md)" };
  const dd = { margin: 0, flex: "none", textAlign: "end", fontVariantNumeric: "tabular-nums" };

  return (
    <section
      aria-labelledby={titleId}
      style={{
        display: "flex", flexDirection: "column", gap: "var(--dt-space-stack-md)",
        padding: "var(--dt-summary-padding)", boxSizing: "border-box", minWidth: 0,
        background: "var(--dt-summary-bg)", color: "var(--dt-text-primary)",
        border: "var(--dt-border-width-default) solid var(--dt-summary-border)",
        borderRadius: "var(--dt-summary-radius)",
        ...style,
      }}
      {...rest}
    >
      <Heading id={titleId} level={headingLevel} size="heading-xs" tone="primary">{title}</Heading>

      {fs && (
        <Progress
          size="sm"
          tone={reached ? "success" : "primary"}
          value={Math.min(Math.max(fs.current, 0), fs.threshold)}
          max={fs.threshold}
          label={message}
        />
      )}

      <dl style={{ margin: 0, display: "flex", flexDirection: "column", gap: "var(--dt-space-stack-xs)" }}>
        {lines.map((line, i) => {
          const kind = KINDS[line.kind] || KINDS.default;
          const discount = line.kind === "discount";
          return (
            <div key={line.label + i} style={row}>
              <dt style={{ minWidth: 0, display: "flex", flexDirection: "column" }}>
                <span style={{ ...role("body-sm"), color: kind.label }}>{line.label}</span>
                {line.hint && <span style={{ ...role("body-xs"), color: "var(--dt-summary-hint-color)" }}>{line.hint}</span>}
              </dt>
              <dd style={dd}>
                <Price
                  amount={discount ? -Math.abs(line.amount) : line.amount}
                  size="sm"
                  currency={currency}
                  locale={locale}
                  style={{ "--dt-price-color": kind.value }}
                />
              </dd>
            </div>
          );
        })}
        <div
          style={{
            ...row,
            paddingBlockStart: "var(--dt-space-stack-sm)",
            marginBlockStart: lines.length ? "var(--dt-space-stack-2xs)" : 0,
            borderBlockStart: lines.length ? "var(--dt-border-width-default) solid var(--dt-summary-divider)" : undefined,
          }}
        >
          <dt style={{ ...role("label-lg"), color: "var(--dt-summary-total-color)" }}>{total.label || "Total"}</dt>
          <dd style={dd}>
            <Price
              amount={total.amount}
              size="lg"
              currency={currency}
              locale={locale}
              style={{ "--dt-price-color": "var(--dt-summary-total-color)" }}
            />
          </dd>
        </div>
      </dl>

      {footer && <div style={{ display: "flex", flexDirection: "column", gap: "var(--dt-space-stack-sm)" }}>{footer}</div>}
    </section>
  );
}