Evidence image
ProAn image of evidence the app holds, such as a screenshot taken while checking the work: a thumbnail button with an enlarge mark, and a caption under it. Pressed, it opens a lightbox with the image large, and Previous and Next through set (the arrow keys too), "Image 3 of 8" as its title, focus kept in it, Escape to close, and focus back on the thumbnail after.
The image is the app's: src is the app's own stored copy, never an address from model output. alt is required, and is the app's description of what the image shows; left empty, the image is named by its place ("Image 3 of 8"). The caption's shows is the checking agent's description of the image, so it is drawn as theirs ("Described by …"), never as a fact; who it was taken signed in as, where and when are the app's facts, each drawn only when given, and "not recorded" when the app says so with null. When the image has no address or doesn't load, it says it isn't available, with the app's description, rather than showing an empty box.
Preview
Loading the preview
Install
First time? Get started sets up the registry and theme. Or with shadcn directly: npx shadcn@latest add @candor/evidence-image
Brings in: bidi, button, chat, dialog, locale, locked, tokens, utils · npm: lucide-react@^1.67.0
Usage
"use client"
import { EvidenceImage, type EvidenceImageData } from "@/components/candor/evidence-image"
const checker = { id: "check", name: "Checking agent", role: "reviewer" }
/*
* Screenshots the app took while checking the work, served from its own store. `alt` is the app's description; `shows`
* is the checking agent's, drawn as theirs. The third has no stored copy, so it says the image isn't available.
*/
const walkthrough: EvidenceImageData[] = [
{
id: "inbox",
src: "/examples/screenshots/approvals-inbox-light-desktop.jpg",
alt: "The approvals inbox with three requests waiting",
shows: "The inbox lists the three waiting requests, newest first.",
describedBy: checker,
signedInAs: "Dana Whitfield",
where: "The test copy",
at: "2026-11-16T14:03:00Z",
},
{
id: "console",
src: "/examples/screenshots/agent-ops-console-light-desktop.jpg",
alt: "The operations console after the approval",
shows: "The run continues once the request is approved.",
describedBy: checker,
signedInAs: "Dana Whitfield",
where: "The test copy",
at: "2026-11-16T14:05:00Z",
},
{ id: "receipt", src: null, alt: "The run's receipt", signedInAs: null, where: "The test copy", at: null },
]
export default function Example() {
return (
<div className="flex flex-wrap gap-4">
{walkthrough.map((image) => (
<EvidenceImage key={image.id} image={image} set={walkthrough} />
))}
</div>
)
}<EvidenceImage>
| Prop | Type | Default | Description |
|---|---|---|---|
| imagerequired | EvidenceImageData | — | The image: the app's address for it, its description, and the caption's parts. |
| set | EvidenceImageData[] | undefined | — | The set the image is in, in order, this one among them: its lightbox walks it, and an image with an empty `alt` is named by its place in it. Left out, the lightbox shows this one alone. |
| onOpen | ((image: EvidenceImageData) => void) | undefined | — | Called when the thumbnail is pressed, in place of opening its own lightbox: for a set whose one lightbox the app (or EvidenceGallery) owns. |
| className | string | undefined | — | Classes for the figure, merged with Candor's. |
<EvidenceLightbox>
The lightbox for a set of evidence images: one image at a time, large, with its caption, "Image 3 of 8" as its title, and Previous and Next through the set. The arrow keys move too (mirrored right to left). At either end the button stays and says why it can't be used, and the arrow key says the same to a screen reader. Focus is kept in the window, Escape closes it, and focus goes back to where it was (or to returnFocusTo's element).
EvidenceImage and EvidenceGallery draw it for you; use it directly for a set the app opens from its own controls.
| Prop | Type | Default | Description |
|---|---|---|---|
| imagesrequired | EvidenceImageData[] | — | The images, in the order Previous and Next walk them. |
| indexrequired | number | — | Which image is shown, from 0. |
| onIndexChangerequired | (index: number) => void | — | Called with the image to show when the person moves. |
| openrequired | boolean | — | Whether the lightbox is open. |
| onOpenChangerequired | (open: boolean) => void | — | Called when the person closes it (Escape, the ×, a press outside). |
| returnFocusTo | ((image: EvidenceImageData) => HTMLElement | null | undefined) | undefined | — | The element to put focus on when it closes, from the image last shown. Left out or returning nothing, focus goes back where it was. |
| className | string | undefined | — | Classes for the window, merged with Candor's. |
Strings
The fixed words, in English by default. Change any of them under evidenceImage in <LocaleProvider strings={{ … }}>; the table is exported as evidenceImageStrings.
| Key | English |
|---|---|
| enlarge | Enlarge: {alt} |
| missing | The image isn’t available. |
| agentWords | The checking agent’s description |
| describedBy | Described by {agent} |
| signedInAs | Signed in as {who} |
| signedInAsUnknown | Signed in as: not recorded |
| whereUnknown | Where: not recorded |
| atUnknown | When: not recorded |
| title | Image |
| titleOf | Image {current} of {total} |
| moved | Image {current} of {total}: {alt} |
| previous | Previous image |
| next | Next image |
| atStart | This is the first image. |
| atEnd | This is the last image. |
Motion
| Moment | Family | What it does |
|---|---|---|
| tint | tint | The thumbnail's border darkens when the pointer is over it, and a ring shows when it takes keyboard focus. |
Set with --cd-motion-evidence-image-<moment>-* in your brand file; the families are in the design reference.
Types
- EvidenceImageData
- One image of evidence, as the app holds it. The image and every fact about it come from the app; only `shows` is the checking agent's words, and it is drawn as theirs.
{ /** Stable within the set. */ id: string; /** * The address of the app's own copy of the image: one it captured or stored and serves. Never an address from model * output, which could point anywhere. Left out or `null`, or when it doesn't load, the image says it isn't available. */ src?: string | null | undefined; /** * What the image shows, written by the app for screen readers and for when the image isn't available: make it * describe the image ("The account list with the new column"). Required; left empty, the image is named only by its * place, "Image 3 of 8". */ alt: string; /** What the image shows, in the checking agent's words: drawn as their description, never as a fact. */ shows?: string | undefined; /** The agent who wrote `shows`, named by the app. Left out, the description says it is the checking agent's. */ describedBy?: AgentIdentity | undefined; /** Who the image was taken signed in as, in the app's words. `null` says it wasn't recorded; left out, it isn't drawn. */ signedInAs?: string | null | undefined; /** Where the image was taken ("the test copy"), in the app's words. `null` says it wasn't recorded; left out, it isn't drawn. */ where?: string | null | undefined; /** When the image was taken. `null` says it wasn't recorded; left out, it isn't drawn. */ at?: Date | string | number | null | undefined; /** The app's group for the image ("Criterion 2", "Step 3"), which EvidenceGallery draws a heading for. */ group?: string | undefined; }
Types from other items
The props above take these. Each is defined by another item; import it from the path shown.
- AgentIdentity from @/lib/candor/chat
{ id: string; /** The displayed name, e.g. "Architect agent". Never derived from model output. */ name: string; role: AgentRole; specialty?: string | undefined; }- Criterion from @/lib/candor/ops
{ id: string; label: string; passed: number; failed: number; /** Pass rate of the baseline run, 0–1. */ baseline: number | null; }- AgentRole from @/lib/candor/chat
- What an agent does: "assistant", "coder", "reviewer"… The app registers each role's glyph and hue (AgentRolesProvider).
string