Price

Install and import

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

Guidelines

An amount of money, formatted for its currency and locale by Intl.NumberFormat, with an optional compare-at price for a sale and a unit such as "/ month".

Use it when

• Showing what something costs: a product card, a cart line, a menu item, a plan, an order total.
• A sale needs the original price beside the new one (compareAt).
• The price is per something: unit="/ month", "each", "/ kg".

Don't use it when

• The number is not money. Use Text with numeric for counts and measurements.
• You need a range ("$20–$40") or "from $20". Compose two Prices, or put "From" in Text before one.

Example

<Price amount={24.5} compareAt={30} />
<Price amount={12} unit="/ month" size="lg" />
<Price amount={1290} currency="EUR" locale="de-DE" />
<Price amount={1200} currency="JPY" locale="ja-JP" />
<Price amount={0} freeLabel="Free delivery" size="sm" />

amount is in major units. Prices stored in minor units must be converted first: cents / 100 for USD, EUR or GBP; a zero-decimal currency such as JPY needs no conversion.

Variants

The locale defaults to the runtime's. Pass locale when server rendering so the server and the browser print the same string and hydration matches. An unknown currency code falls back to the number followed by the code.

Composition

Inline: it renders a <span>, so it sits in a line of text, a card's footer or a table cell. It wraps between the amount, the compare-at price and the unit when space is short, never inside one of them. Other commerce components (product cards, cart lines, menus) render their prices with it.

Tokens

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

• --dt-price-color (--dt-text-primary): the amount.
• --dt-price-sale-color (--dt-text-danger): the amount when it is on sale.
• --dt-price-compare-color (--dt-text-tertiary): the struck compare-at price.
• --dt-price-unit-color (--dt-text-secondary): the unit.

Type comes from the semantic roles: --dt-text-label-md-*, --dt-text-label-lg-* or --dt-text-heading-md-* for the amount, and --dt-text-body-xs-* or --dt-text-body-sm-* for the compare-at price and the unit. Figures are tabular, so prices in a column line up.

Accessibility

• On a sale, the visible amount and the struck price are hidden from assistive technology and a visually hidden span reads "Was $30.00, now $24.50", using the same formatted strings the page shows. A strikethrough alone is not announced by most screen readers, so without this the two prices would read as one confusing number.
• The sale colour is never the only signal: the struck compare-at price carries it too.
• The unit is ordinary text and is read after the price.

Content

• unit is lowercase and short: "/ month", "each", "/ kg", "per person". Put a space after the slash.
• freeLabel is sentence case: "Free", "Free delivery", "Included".
• Don't add the currency code yourself; Intl places the symbol where the locale expects it (12,90 € in German, €12.90 in Irish English).

Props

The typed contract, from Price.d.ts.

import * as React from "react";

/** An amount of money, formatted for its currency and locale, with an optional compare-at price and unit. */
export interface PriceProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, "children"> {
  /**
   * The amount in major units: 24.5 for $24.50, 1200 for ¥1,200. Prices stored in
   * minor units (cents) must be converted first: divide by 100 for USD or EUR, and
   * leave a zero-decimal currency such as JPY as it is.
   */
  amount: number;
  /** ISO 4217 currency code, passed to Intl.NumberFormat. @default "USD" */
  currency?: string;
  /**
   * BCP 47 locale for the format, e.g. "de-DE" or "ja-JP". Defaults to the runtime's
   * locale; set it when server rendering so the server and the browser print the same.
   */
  locale?: string;
  /**
   * The original price, in the same units as amount. When it is greater than amount it
   * shows struck through after the amount, and the amount takes the sale colour.
   */
  compareAt?: number;
  /** What the price is per, shown after it, smaller and secondary: "/ month", "each", "/ kg". */
  unit?: string;
  /** @default "md" */
  size?: "sm" | "md" | "lg";
  /** Shown instead of a formatted zero when amount is 0. @default "Free" */
  freeLabel?: string;
}

export declare function Price(props: PriceProps): React.JSX.Element;

Tokens it reads

Every custom property Price.jsx resolves, read from the source: 4 component, 151 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";

/* Each size is a type role for the amount and a smaller one for the struck
   compare-at price and the unit beside it. */
const SIZES = {
  sm: { amount: "label-md", aside: "body-xs" },
  md: { amount: "label-lg", aside: "body-sm" },
  lg: { amount: "heading-md", aside: "body-sm" },
};

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

/* One formatter per currency and locale. An unknown currency code makes
   Intl throw; the amount still shows, with the code after it. */
function useFormat(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 Price({
  amount,
  currency = "USD",
  locale,
  compareAt,
  unit,
  size = "md",
  freeLabel = "Free",
  style,
  ...rest
}) {
  const format = useFormat(currency, locale);
  const s = SIZES[size] || SIZES.md;
  const shown = amount === 0 ? freeLabel : format(amount);
  const onSale = typeof compareAt === "number" && compareAt > amount;
  const was = onSale ? format(compareAt) : null;

  return (
    <span
      style={{
        position: "relative",
        display: "inline-flex", alignItems: "baseline", flexWrap: "wrap",
        columnGap: "var(--dt-space-inline-xs)",
        fontVariantNumeric: "tabular-nums",
        ...style,
      }}
      {...rest}
    >
      {onSale && <VisuallyHidden>{`Was ${was}, now ${shown}`}</VisuallyHidden>}
      <span
        aria-hidden={onSale || undefined}
        style={{ ...role(s.amount), color: onSale ? "var(--dt-price-sale-color)" : "var(--dt-price-color)", whiteSpace: "nowrap" }}
      >
        {shown}
      </span>
      {onSale && (
        <s aria-hidden="true" style={{ ...role(s.aside), color: "var(--dt-price-compare-color)", whiteSpace: "nowrap" }}>
          {was}
        </s>
      )}
      {unit && (
        <span style={{ ...role(s.aside), color: "var(--dt-price-unit-color)", whiteSpace: "nowrap" }}>{unit}</span>
      )}
    </span>
  );
}