Skip to content

Patterns / Agree and start

Agree and start: the last confirmation before money is spent

Before an agent spends money, the person should see what they are agreeing to and say yes to an amount, not to a word like OK. Use this as the last confirmation before money is spent: starting a paid run, raising a cap, approving a round of work.

Open an AlertDialog. Its title asks the question and its description says that nothing is spent until they agree. Restate the facts in a DetailsList: what will be done, the estimate (labelled as one), the most that may be spent and where. The action is an AmountButton whose words carry the amount ("Agree and start · up to $25.00"), drawn from the same figure as the list, so the two can't disagree. Cancel is beside it.

Focus starts on Cancel, as AlertDialog's always does, Escape answers Cancel, and a click outside doesn't close it, so no stray key press or click agrees. If the amount changes while the dialog is open, the button locks for half a second and says the new amount, so a press meant for the old figure can't land. While the agreement isn't complete, the button is locked with the reason.

The components

  • Alert dialogProThe dialog that stops for the decision: focus on Cancel, Escape cancels, a click outside doesn't dismiss it.
  • Amount buttonProThe one action, which names the amount, locks briefly when it changes and hands back the amount the person saw (Pro).
  • Details listProThe facts being agreed to, as labelled rows: what, the estimate, the most that may be spent, where (Pro).
  • MoneyProAn amount anywhere else on the page, to the cent with `decimals="always"`, an estimate marked as one (Pro).
  • Money inputProWhere the person sets the most that may be spent before they agree, with your estimate drawn against it (Pro).

See it working

The code

The dialog: the facts from your agreement, Cancel focused first, and the amount on the one button that agrees.

TSX · agree-and-start.tsx
"use client"

import * as React from "react"
import {
  AlertDialog,
  AlertDialogCancel,
  AlertDialogContent,
  AlertDialogDescription,
  AlertDialogFooter,
  AlertDialogHeader,
  AlertDialogTitle,
  AlertDialogTrigger,
} from "@/components/candor/ui/alert-dialog"
import { Button } from "@/components/candor/ui/button"
import { AmountButton } from "@/components/candor/amount-button"
import { DetailsList } from "@/components/candor/details-list"
import { useFormat } from "@/components/candor/locale"
import { formatMoney } from "@/lib/candor/ops"

type Agreement = {
  promises: number
  /** Your server's words for the estimate ("about $18–$24"): an estimate, so it is labelled as one. */
  estimateText: string
  /** The most that may be spent, from the agreement: the one figure the list and the button both show. */
  cap: number
  environment: string
  /** Why it can't start yet, while the agreement isn't complete. */
  incomplete: string | null
}

export function AgreeAndStart({ agreement, onAgree }: { agreement: Agreement; onAgree: (cap: number) => Promise<void> }) {
  const [agreeOpen, setAgreeOpen] = React.useState(false)
  const format = useFormat()
  const cap = formatMoney(format.number, agreement.cap, "USD", { decimals: "always" })
  return (
    <AlertDialog open={agreeOpen} onOpenChange={setAgreeOpen}>
      <AlertDialogTrigger render={<Button />}>Review and start</AlertDialogTrigger>
      <AlertDialogContent>
        <AlertDialogHeader>
          <AlertDialogTitle>Agree and start?</AlertDialogTitle>
          <AlertDialogDescription>Nothing is spent until you agree.</AlertDialogDescription>
        </AlertDialogHeader>
        <DetailsList
          groups={[
            {
              id: "agreement",
              title: "What you're agreeing to",
              collapsible: false,
              rows: [
                { label: "Promises", value: String(agreement.promises) },
                { label: "Estimate", value: agreement.estimateText },
                { label: "The most I may spend", value: cap },
                { label: "Where", value: agreement.environment },
              ],
            },
          ]}
        />
        <AlertDialogFooter>
          {/* Focus starts here, so no key press by accident agrees. */}
          <AlertDialogCancel>Not yet</AlertDialogCancel>
          <AmountButton
            amount={agreement.cap}
            decimals="always"
            label="Agree and start · up to {amount}"
            locked={agreement.incomplete}
            onConfirm={async (seen) => {
              // Your server starts the work only if `seen` is still the agreement's cap.
              await onAgree(seen)
              setAgreeOpen(false)
            }}
          />
        </AlertDialogFooter>
      </AlertDialogContent>
    </AlertDialog>
  )
}

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

  • Write the amount on the button and in the list from one value. formatMoney with { decimals: "always" } writes the list's text as Money writes the button's.
  • onConfirm gets the amount the person saw. Send it with the request, and have your server start only if it is still the agreement's amount.
  • Use it for the moment money is committed, not for every step. A choice between answers is a decision (DecisionCard), not this; a step that can't be undone and costs nothing is HoldToConfirm's or a destructive AlertDialogAction's.