Approval Card
SaveAsk a person to approve or reject an agent action: the state in words, the question, what will run, and two decisions, with calm resolved states and duplicate-click protection while a decision is saved.
- Category
- Agent
- Version
- 0.3.0
- Frameworks
- Next.js, Vite + React
- Styling
- Tailwind CSS v4
Preview
Needs your approval
Open a pull request?
The agent wants to push a branch and open a pull request in acme/docs.
git push origin docs/rate-limits gh pr create --title "Update rate limits"
Installation
npx @shakenui/cli add approval-cardReview the plan first. A dry run lists every file and package without changing anything:
npx @shakenui/cli add approval-card --dry-runUsage
"use client";
import { useState } from "react";
import type { ApprovalStatus } from "@/components/shaken/agent/agent-run";
import { ApprovalCard } from "@/components/shaken/agent/approval-card";
export default function ApprovalCardExample() {
const [status, setStatus] = useState<ApprovalStatus>("pending");
// Replace with a call to your backend, which must verify the user may approve this action.
const record = (decision: "approved" | "rejected") => new Promise<void>((resolve) => setTimeout(() => (setStatus(decision), resolve()), 600));
return (
<ApprovalCard
className="w-full max-w-md"
title="Open a pull request?"
description="The agent wants to push a branch and open a pull request in acme/docs."
detail={'git push origin docs/rate-limits\ngh pr create --title "Update rate limits"'}
status={status}
onApprove={() => record("approved")}
onReject={() => record("rejected")}
/>
);
}States
Every state, rendered from local fixture data.
Needs your approval
Open a pull request?
Push docs/rate-limits and open a PR in acme/docs.
gh pr create --title "Update rate limits"
Approved
Open a pull request?
Push docs/rate-limits and open a PR in acme/docs.
gh pr create --title "Update rate limits"
The agent can continue.
Rejected
Open a pull request?
Push docs/rate-limits and open a PR in acme/docs.
gh pr create --title "Update rate limits"
Nothing ran.
Expired
Open a pull request?
Push docs/rate-limits and open a PR in acme/docs.
gh pr create --title "Update rate limits"
No decision was made in time. Nothing ran.
API
| Prop | Type | Default | Description |
|---|---|---|---|
| title | ReactNode | — | The question, phrased as what the agent wants to do. |
| status | "pending" | "approved" | "rejected" | "expired" | — | Decision state. Approve and Reject show only while pending. |
| description | ReactNode | — | Context for the decision. |
| detail | string | — | The exact action, e.g. a command or diff, shown in a well. It recedes once the request is rejected or expires. |
| onApprove / onReject | () => void | Promise<void> | — | Called once per decision; both buttons ignore clicks until it settles. Errors show a retry message. |
| approveLabel / rejectLabel | string | "Approve" / "Reject" | Button text. |
| detailLabel | string | "What will run" | Accessible caption for detail. |
| outcome | ReactNode | — | Replaces the sentence shown after a decision, for example "Approved by Dana at 14:02." |
Accessibility
- The state leads the card as a live region with a text label and glyph ("Needs your approval", "Approved"), not color alone.
- The detail well has an accessible caption (detailLabel).
- While a decision is saving, the chosen button shows a busy state and keeps focus; repeated clicks are ignored.
- After a decision, the buttons give way to a sentence that states the outcome (for example "Nothing ran."). Transitions are removed with reduced motion.
- The card only reports a decision. Your backend must verify the approval and the user's authorization before acting.
Files
Installed into src/components/shaken, or components/shaken when the project has no src directory.
src/components/shaken/agent/approval-card.tsxapproval-card- Also installs button@0.2.1registry dependency
- Also installs agent-run@0.1.2registry dependency
- npm packages: noneReact and Tailwind CSS v4 required
Source
The exact source the CLI installs, from /r/items/react/approval-card/0.3.0.json.
agent/approval-card.tsxShowHide
"use client";
import { type ComponentProps, type ReactNode, useRef, useState } from "react";
import { Button } from "../ui/button";
import type { ApprovalStatus } from "./agent-run";
const statuses: Record<ApprovalStatus, { label: string; outcome: string; tone: string }> = {
pending: { label: "Needs your approval", outcome: "", tone: "text-amber-700 dark:text-amber-400" },
approved: { label: "Approved", outcome: "The agent can continue.", tone: "text-emerald-700 dark:text-emerald-400" },
rejected: { label: "Rejected", outcome: "Nothing ran.", tone: "text-red-700 dark:text-red-400" },
expired: { label: "Expired", outcome: "No decision was made in time. Nothing ran.", tone: "text-zinc-500" },
};
const ease = "ease-[cubic-bezier(0.23,1,0.32,1)]";
const enter = `transition-[opacity,translate] duration-200 ${ease} starting:opacity-0 motion-safe:starting:translate-y-1 motion-reduce:transition-none`;
export interface ApprovalCardProps extends Omit<ComponentProps<"section">, "title" | "children"> {
/** The question, phrased as what the agent wants to do. */
title: ReactNode;
status: ApprovalStatus;
description?: ReactNode;
/** What will happen if approved, such as a command or diff. Shown as preformatted text. */
detail?: string;
/** Called once per decision. While it runs, both buttons ignore further clicks. */
onApprove?: () => void | Promise<void>;
onReject?: () => void | Promise<void>;
approveLabel?: string;
rejectLabel?: string;
/** Caption for `detail`. */
detailLabel?: string;
/** Replaces the sentence shown after a decision, for example "Approved by Dana at 14:02." */
outcome?: ReactNode;
}
/**
* Asks a person to approve or reject an agent action: the question, what will run, then two
* decisions. The UI only reports the decision: your backend must verify the approval and the
* user's authorization before acting.
*/
export function ApprovalCard({
title,
status,
description,
detail,
onApprove,
onReject,
approveLabel = "Approve",
rejectLabel = "Reject",
detailLabel = "What will run",
outcome,
className,
...props
}: ApprovalCardProps) {
const [submitting, setSubmitting] = useState<"approve" | "reject" | null>(null);
const [error, setError] = useState<string | null>(null);
const inFlight = useRef(false);
const meta = statuses[status];
const pending = status === "pending";
async function decide(decision: "approve" | "reject") {
// A ref (not state) guards against double clicks that land before React re-renders.
if (inFlight.current || status !== "pending") return;
inFlight.current = true;
setSubmitting(decision);
setError(null);
try {
await (decision === "approve" ? onApprove : onReject)?.();
} catch {
setError("Your decision was not saved. Try again.");
} finally {
inFlight.current = false;
setSubmitting(null);
}
}
return (
<section
aria-label={typeof title === "string" ? `Approval: ${title}` : "Approval request"}
data-status={status}
className={[
"rounded-xl border border-zinc-950/10 bg-white p-4 text-zinc-950 shadow-[0_1px_2px_rgb(0_0_0/0.04)]",
"dark:border-white/10 dark:bg-black dark:text-white dark:shadow-[inset_0_1px_0_rgb(255_255_255/0.06)]",
className,
]
.filter(Boolean)
.join(" ")}
{...props}
>
{/* The state, in words and a glyph, leads the card; it is the live region. */}
<p role="status" className={`flex items-center gap-1.5 text-xs font-medium ${meta.tone}`}>
<DecisionGlyph key={status} status={status} />
<span key={`${status}-label`} className={`transition-opacity duration-200 ${ease} starting:opacity-0 motion-reduce:transition-none`}>
{meta.label}
</span>
</p>
<h3 className="mt-2 text-[15px] leading-snug font-semibold tracking-[-0.01em] text-pretty">{title}</h3>
{description ? <p className="mt-1 text-sm leading-relaxed text-pretty text-zinc-600 dark:text-zinc-400">{description}</p> : null}
{detail ? (
<figure
className={[
"mt-3 transition-opacity duration-200 ease-out motion-reduce:transition-none",
// Once rejected or expired the command never ran, so it recedes.
status === "rejected" || status === "expired" ? "opacity-55" : "",
].join(" ")}
>
<figcaption className="sr-only">{detailLabel}</figcaption>
<pre
className="overflow-x-auto rounded-lg border border-zinc-950/[0.07] bg-zinc-950/[0.02] px-3 py-2.5 font-mono text-xs leading-relaxed text-zinc-800 dark:border-white/[0.08] dark:bg-white/[0.02] dark:text-zinc-300"
>
{detail}
</pre>
</figure>
) : null}
{pending ? (
<div className="mt-4">
<div className="grid grid-cols-2 gap-2 sm:flex sm:justify-end">
<Button
size="sm"
variant="ghost"
loading={submitting === "reject"}
disabled={submitting === "approve"}
onClick={() => decide("reject")}
className="border border-zinc-950/10 sm:border-transparent dark:border-white/10 sm:dark:border-transparent"
>
{rejectLabel}
</Button>
<Button size="sm" loading={submitting === "approve"} disabled={submitting === "reject"} onClick={() => decide("approve")}>
{approveLabel}
</Button>
</div>
{error ? (
<p role="alert" className={`mt-3 text-sm text-red-600 dark:text-red-400 ${enter}`}>
{error}
</p>
) : null}
</div>
) : (
<p key={status} className={`mt-3 text-sm text-zinc-500 ${enter}`}>
{outcome ?? meta.outcome}
</p>
)}
</section>
);
}
/** The shared status shapes at 14px: pause bars while waiting, then check, x, or slash. */
function DecisionGlyph({ status }: { status: ApprovalStatus }) {
// A 16 unit box drawn at 14px: a 1.6 stroke renders at 1.4px.
const stroke = { fill: "none", stroke: "currentColor", strokeWidth: 1.6, strokeLinecap: "round", strokeLinejoin: "round" } as const;
return (
<svg
aria-hidden="true"
viewBox="0 0 16 16"
{...stroke}
className={`size-3.5 shrink-0 transition-[opacity,scale] duration-200 ${ease} starting:opacity-0 motion-safe:starting:scale-90 motion-reduce:transition-none`}
>
<circle cx="8" cy="8" r="6.25" />
{status === "pending" ? (
<path d="M6.6 5.9v4.2M9.4 5.9v4.2" />
) : status === "approved" ? (
<path
d="m5.35 8.25 1.75 1.75 3.55-3.75"
pathLength={1}
strokeDasharray="1"
className={`[stroke-dashoffset:0] transition-[stroke-dashoffset] delay-75 duration-300 ${ease} starting:[stroke-dashoffset:1] motion-reduce:transition-none`}
/>
) : status === "rejected" ? (
<path d="m6.1 6.1 3.8 3.8m0-3.8-3.8 3.8" />
) : (
<path d="m5.6 10.4 4.8-4.8" />
)}
</svg>
);
}