Skip to content
Shaken UI
Sign in

Approval Card

Save

Ask 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

Approval Card preview

Needs your approval

Open a pull request?

The agent wants to push a branch and open a pull request in acme/docs.

What will run
git push origin docs/rate-limits
gh pr create --title "Update rate limits"

Installation

npx @shakenui/cli add approval-card

Review the plan first. A dry run lists every file and package without changing anything:

npx @shakenui/cli add approval-card --dry-run

Usage

approval-card-example.tsx
"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.

Approval Card states

Needs your approval

Open a pull request?

Push docs/rate-limits and open a PR in acme/docs.

What will run
gh pr create --title "Update rate limits"

Approved

Open a pull request?

Push docs/rate-limits and open a PR in acme/docs.

What will run
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.

What will run
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.

What will run
gh pr create --title "Update rate limits"

No decision was made in time. Nothing ran.

API

PropTypeDefaultDescription
titleReactNode—The question, phrased as what the agent wants to do.
status"pending" | "approved" | "rejected" | "expired"—Decision state. Approve and Reject show only while pending.
descriptionReactNode—Context for the decision.
detailstring—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 / rejectLabelstring"Approve" / "Reject"Button text.
detailLabelstring"What will run"Accessible caption for detail.
outcomeReactNode—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.tsxShow
agent/approval-card.tsx
"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>
  );
}