# Guardrail Notice (/docs/agent-ui/components/guardrail-notice)

Use a guardrail notice where a response would have been when a safety or content policy stopped it, or beside results it filtered. It's a [notice](./notice.mdx) with the policy reason and an optional detail behind **Why?**.

<Example caption="Press Why? to read the policy, and press it again to hide it. Press Dismiss to remove the blocked notice.">
<Basic />

```tsx
"use client";
import { useState } from "react";
import { GuardrailNotice } from "@/components/ui/guardrail-notice";

export default function GuardrailNoticeExample() {
  const [shown, setShown] = useState(true);

  return (
    <div className="flex w-full max-w-xl flex-col gap-3">
      {shown ? (
        <GuardrailNotice
          blocking
          label="Model output withheld"
          reason="The response included personal data."
          detail="Your organization's policy blocks responses that contain email addresses or phone numbers."
          onDismiss={() => setShown(false)}
        />
      ) : (
        <button
          type="button"
          className="self-start rounded-md border border-[var(--kind-color-border)] px-2.5 py-1 text-sm"
          onClick={() => setShown(true)}
        >
          Show the notice again
        </button>
      )}
      <GuardrailNotice
        variant="info"
        label="Some results hidden"
        reason="Two search results matched a content filter."
        detail="Filtered results come from sites your organization has blocked."
      />
    </div>
  );
}
```
</Example>

## Installation [#installation]

```bash tab="React"
npx shadcn@latest add @kind-ui/guardrail-notice
```

```bash tab="Web Components"
npx shadcn@latest add @kind-ui/guardrail-notice-web
```

## Composition [#composition]

```text
GuardrailNotice
├── GuardrailNoticeIcon
├── GuardrailNoticeTitle
├── GuardrailNoticeReason
├── GuardrailNoticeDetailTrigger
├── GuardrailNoticeDetail
├── GuardrailNoticeDescription
├── GuardrailNoticeActions
└── GuardrailNoticeDismiss
```

`GuardrailNotice` renders these parts. `GuardrailNoticeTitle` shows the `label`, else "Response blocked" or "Response filtered", and `GuardrailNoticeReason` the `reason`. `GuardrailNoticeDetailTrigger` is the **Why?** button that shows and hides `GuardrailNoticeDetail`, both rendered only with a `detail`. `GuardrailNoticeDescription` holds any `children`, for more text under the reason. The icon, actions and Dismiss work as in Notice. To arrange the parts yourself, render them inside `GuardrailNoticeRoot`.

## Usage [#usage]

### Blocking [#blocking]

Pass `blocking` when the guardrail stopped the response. The notice is then an alert, and its announcement interrupts what a screen reader is saying. Without it the notice is a note that waits its turn, for content that was only filtered. The variant defaults to `"warning"`; pass `variant="info"` for a quieter filter notice.

### Detail [#detail]

Pass `detail` to add **Why?**. Pressing it, or Enter or Space on it, shows the detail, and find in page shows it too when it matches hidden text. Pass `defaultOpen` to start with it shown, or `open` with `onOpenChange` to control it; `onOpenChange` gets `"trigger-press"`, `"find-in-page"` or `"imperative"`.

```tsx
<GuardrailNotice
  blocking
  label="Model output withheld"
  reason="The response included personal data."
  detail="Your organization's policy blocks responses that contain email addresses or phone numbers."
/>
```

At full motion the detail slides open; under `prefers-reduced-motion`, or with `motion="reduced"`, it fades in over 120 ms, and with `motion="none"` it shows at once.

### Dismiss and Announcements [#dismiss-and-announcements]

**Dismiss**, `focusFallback` and the announcements work as in [Notice](./notice.mdx): a guardrail notice added after the page loads announces its title once.

## API Reference [#api-reference]

### GuardrailNoticeOptions

| Prop             | Type                                                                                              | Description                                                                                                                                                           |
| ---------------- | ------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `onDismiss?`     | `(() => unknown) \| undefined`                                                                    | Called once Dismiss has faded the notice out: remove the notice then. Shows Dismiss while set. Return a promise to wait for it: a rejection brings the notice back.   |
| `focusFallback?` | `(() => HTMLElement \| null \| undefined) \| undefined`                                           | Where focus goes when Dismiss is pressed. Defaults to the next element Tab reaches after the notice, else the last one before it.                                     |
| `motion?`        | `"auto" \| "none" \| "reduced"`                                                                   | How the notice comes in and leaves: at full motion it rises in and fades out; reduced motion only fades. `"auto"` follows `prefers-reduced-motion`. Default: `"auto"` |
| `variant?`       | `"error" \| "info" \| "success" \| "warning"`                                                     | How the notice reads: its icon and colors. Default: `"warning"`                                                                                                       |
| `label?`         | `string \| undefined`                                                                             | The notice's title, which names it. Defaults to "Response blocked" while `blocking`, else "Response filtered".                                                        |
| `reason?`        | `string \| undefined`                                                                             | The policy reason, in a sentence.                                                                                                                                     |
| `detail?`        | `string \| undefined`                                                                             | More about the policy, shown under "Why?". Without it, there's no "Why?".                                                                                             |
| `blocking?`      | `boolean \| undefined`                                                                            | Whether the guardrail stopped the response. A blocking notice is an alert and its announcement interrupts; otherwise it's a note, as Notice is. Default: `false`      |
| `open?`          | `boolean \| undefined`                                                                            | Whether the detail shows. Passing it controls it: change it in `onOpenChange`.                                                                                        |
| `defaultOpen?`   | `boolean \| undefined`                                                                            | Whether the detail shows at first, when `open` isn't passed. Default: `false`                                                                                         |
| `onOpenChange?`  | `((open: boolean, details: ChangeDetails<GuardrailNoticeOpenChangeReason>) => void) \| undefined` | Called when the detail opens or closes, with what caused it.                                                                                                          |

### Agent [#agent]

An agent connected with `createAgent` finds the notice by its title and reads `open`. `expand()` and `collapse()` show and hide the detail, offered while there is one, and `dismiss()` does what **Dismiss** does, offered while `onDismiss` is set. Like any component with a button, it also has UI SDK's generic `press`.

### GuardrailNoticeAgentActions

| Prop       | Type                           | Description                                                                                                             |
| ---------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| `dismiss`  | `(() => void) \| undefined`    | Moves focus out of the notice, fades it out, then calls `onDismiss`, as Dismiss does. Offered while `onDismiss` is set. |
| `expand`   | `(() => boolean) \| undefined` | Shows the detail. Offered while there is one. Returns whether the change was accepted.                                  |
| `collapse` | `(() => boolean) \| undefined` | Hides the detail. Offered while there is one. Returns whether the change was accepted.                                  |

<Caption>
Runs in React and Web Components. On `<kind-guardrail-notice>`, props are kebab-case attributes, and `open` and `focusFallback` are properties; `onOpenChange` is the `openchange` event. The element fills in its parts, and Dismiss follows any `<kind-guardrail-notice-actions>` you write inside it. The `can-dismiss` attribute shows Dismiss, which fires `dismiss` once the notice has faded.
</Caption>