Skip to content

Patterns / Cost basis note

Say why costs are estimates

Some costs can't be measured: work on a subscription reports no charge per run, so the app estimates it. The figures should say they are estimates, and the page should say why once, in your product's words, beside them.

Mark each figure with Money's estimated, which adds a visible "est." and says "estimated" to screen readers. Then put an Alert above them with your sentence: what the cost basis is, and what would make the figures exact. Give its description an id and point the table or group holding the figures at it with aria-describedby, so a screen reader hears the reason with the figures.

The wording is yours. Candor has no string for it, because the basis (a subscription, a plan, a key) is your product's, and a component would be one sentence of your words.

The components

  • AlertFreeThe note itself, with a title and your sentence; `role="note"` keeps it from being read out on its own when the page draws.
  • MoneyProEach figure, with `estimated` for its "est." mark and the word for screen readers; a figure not measured yet says so (Pro).

See it working

The code

A month's spend: the note in your words, its id on the table, and each figure marked as an estimate.

TSX · spend-this-month.tsx
"use client"

import * as React from "react"
import { Info } from "lucide-react"
import { Alert, AlertDescription, AlertTitle } from "@/components/candor/ui/alert"
import { Money } from "@/components/candor/money"

/** One line of spend, from your server. `cost` is null while it isn't measured. */
type SpendLine = { id: string; name: string; cost: number | null }

export function SpendThisMonth({ lines, total, estimated, basisNote }: {
  lines: SpendLine[]
  total: number | null
  /** True when the figures are your estimates, not charges (work on a subscription that reports no cost). */
  estimated: boolean
  /** Why they are estimates, in your product's words: your cost basis and what would make them exact. */
  basisNote: string
}) {
  const noteId = React.useId()
  return (
    <section className="flex flex-col gap-3">
      {estimated && (
        // A note that is part of the page, not news: role "note", so it isn't read out on its own when it appears.
        <Alert role="note">
          <Info aria-hidden />
          <AlertTitle>These figures are estimates</AlertTitle>
          <AlertDescription id={noteId}>{basisNote}</AlertDescription>
        </Alert>
      )}
      {/* The table points at the note, so a screen reader hears why its figures are estimates. */}
      <table aria-describedby={estimated ? noteId : undefined} className="w-full text-sm">
        <caption className="text-start font-medium">Spend this month</caption>
        <thead className="sr-only">
          <tr>
            <th scope="col">Item</th>
            <th scope="col">Cost</th>
          </tr>
        </thead>
        <tbody>
          {lines.map((line) => (
            <tr key={line.id}>
              <td>{line.name}</td>
              {/* Each figure keeps its own "est." mark; the note explains it, it doesn't replace it. */}
              <td className="text-end">
                <Money amount={line.cost} decimals="always" estimated={estimated} />
              </td>
            </tr>
          ))}
        </tbody>
        <tfoot>
          <tr>
            <th scope="row" className="text-start">
              Total
            </th>
            <td className="text-end font-medium">
              <Money amount={total} decimals="always" estimated={estimated} />
            </td>
          </tr>
        </tfoot>
      </table>
    </section>
  )
}

Install

With the candor-ui CLI

Each component brings in what it depends on. The free ones install as they are; Pro and Premium ones need a licence key.

Good to know

  • The note explains the per-figure mark; it doesn't replace it. A figure read on its own, in a list or a popover, still says it is estimated.
  • Put aria-describedby on an element a screen reader announces, such as a table, a group with a name or a control; on a plain span many don't read it.
  • When the basis changes (the person adds a key, say) and the figures become measured, take the note and the marks away together.