Skip to content
Tier

Read back

Pro

An inline receipt for something the agent saved: a record's name, a field, a setting. It shows the value the service read back after the save, not the value that was sent, so it never claims more than the service confirms.

  • pending: it says it is checking. It never says saved before the read-back arrives. Its sentence may name the value that was sent (sent, as {sent}), never as saved.
  • saved: the value as the service read it back, in the app's sentence ("I named it {value}"), marked saved, with an optional action such as Rename. Set it only from the service's read-back. Without a value, it says the value read back isn't known rather than showing one.
  • failed: what is still true ("I couldn’t save the name; it’s still Untitled"), with the service's reason when the app has one. When the app doesn't know the value now, it says that rather than guessing.

Each state has its own icon and words, not a colour alone. Values are drawn as plain text in an isolate (<bdi>), with bidi controls marked, since a model may have written them. The sentence sits in one status region for the receipt's life, so a change of state is announced once, politely; nothing is announced when it first appears. The action sits outside the region, and is hidden while pending.

Follows SettlingCard's model: pending, then settled or failed, only on the service's word.

Markdown

Preview

Loading the preview

Install

With the Candor CLI

First time? Get started sets up the registry and theme. Or with shadcn directly: npx shadcn@latest add @candor/read-back

Brings in: bidi, button, locale, locked, tokens, utils · npm: lucide-react@^1.67.0

Usage

TSX · The example above
"use client"

import * as React from "react"
import { ReadBack, type ReadBackState } from "@/components/candor/read-back"
import { Button } from "@/components/candor/ui/button"

/** `value` is what the service read back after the save, not what was sent. */
export default function Example() {
  const [state, setState] = React.useState<ReadBackState>("pending")
  return (
    <div className="flex max-w-lg flex-col gap-3">
      <ReadBack
        state={state}
        field="name"
        value="Renewal Risk Board"
        previous="Untitled"
        failure="A board with that name already exists."
        messages={{ saved: "I named it {value}", failed: "I couldn’t save the name; it’s still {previous}" }}
        action={{ label: "Rename", onAction: () => {} }}
      />
      <div className="flex gap-2">
        {(["pending", "saved", "failed"] as const).map((s) => (
          <Button key={s} size="xs" variant="outline" aria-pressed={state === s} onClick={() => setState(s)}>
            {s}
          </Button>
        ))}
      </div>
    </div>
  )
}

<ReadBack>

PropTypeDefaultDescription
staterequiredReadBackState—Where it stands: "pending" until the service reads the value back, "saved" once it has, "failed" if it wasn't saved.
fieldrequiredstring—What was saved, in the app's words, lower case for the middle of a sentence: "name", "stage".
valuestring | null | undefined—The value as the service read it back, not as it was sent. Shown when saved; `null` or "" reads "(empty)", and left out, the receipt says the value read back isn't known. Ignored while pending, so a value sent but not yet read back is never shown as saved: name that one with `sent`.
sentstring | null | undefined—The value that was sent, for the pending sentence's `{sent}` only ("Renaming it to {sent}…"). Never shown once saved or failed, and never as the saved value.
previousstring | null | undefined—What the value still is after a failure, as the service last read it. Left out, the failure says the current value isn't known; `null` or "" reads "(empty)".
failurestring | undefined—Why the save failed, in the service's own words; shown after the failure sentence.
messagesReadBackMessages | undefined—The app's own sentences for this receipt, in place of the defaults: `{ saved: "I named it {value}" }`.
actionReadBackAction | undefined—A button beside the receipt once it has settled, such as Rename. Hidden while pending.
classNamestring | undefined—Classes, merged with Candor's.

Strings

The fixed words, in English by default. Change any of them under readBack in <LocaleProvider strings={{ … }}>; the table is exported as readBackStrings.

KeyEnglish
pendingChecking that the {field} was saved…
savedThe {field} is now {value}
savedUnknownThe {field} was saved, but the value read back isn’t known
savedMark(saved)
failedCouldn’t save the {field}; it’s still {previous}
failedUnknownCouldn’t save the {field}. What it is now isn’t known.
reasonReason: {reason}
empty(empty)

Types

ReadBackState
Where a saved value stands: sent and not yet read back, read back by the service, or not saved.
"pending" | "saved" | "failed"
ReadBackMessages
The app's own sentences for one receipt, each with `{field}`, and `{value}` (the read-back) or `{previous}` where they go. `pending` takes `{sent}` instead: the value sent, never the read-back.
{ /** In place of "The {field} is now {value}": "I named it {value}". */ saved?: string | undefined; /** In place of "Couldn’t save the {field}; it’s still {previous}": "I couldn’t save the name; it’s still {previous}". */ failed?: string | undefined; /** In place of "Couldn’t save the {field}. What it is now isn’t known.", used when `previous` is left out. */ failedUnknown?: string | undefined; /** In place of "The {field} was saved, but the value read back isn’t known", used when `value` is left out. */ savedUnknown?: string | undefined; /** * In place of "Checking that the {field} was saved…". It may hold `{sent}`, the value that was sent and not yet * read back ("Renaming it to {sent}…"); `{value}` isn't filled while pending. */ pending?: string | undefined; }
ReadBackAction
A button beside the receipt, such as Rename, in the app's words.
{ /** The button's words: "Rename". */ label: string; /** Called when it's pressed. */ onAction: () => void; /** Why it can't be used right now, if it can't. The button stays and says why. */ locked?: string | null | undefined; }