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.
"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
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.
formatMoneywith{ decimals: "always" }writes the list's text as Money writes the button's. onConfirmgets 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.