# Feedback (/docs/agent-ui/components/feedback)

Use feedback in a message's actions, so a person can tell you which answers helped. It's two quiet thumbs, and once one is pressed, an **Add a comment** button that opens a small box to write in.

<Example caption="Press the thumbs up, then Add a comment. Write a few words and press Send: the box closes and a thank-you takes the button's place.">
<Basic />

```tsx
"use client";
import { useState } from "react";
import { Feedback } from "@/components/ui/feedback";
import { KindToolbar, KindToolbarButton } from "@/components/ui/internal/toolbar";
import { Message, MessageContent, MessageCopy, MessageToolbar } from "@/components/ui/message";

const reply = "Retry with exponential backoff, and cap the number of attempts.";

export default function FeedbackExample() {
  const [commentSent, setCommentSent] = useState(false);

  return (
    <Message aria-label="Assistant message" messageRole="assistant" text={reply} className="w-full max-w-xl">
      <MessageContent>{reply}</MessageContent>
      <MessageToolbar>
        <KindToolbar aria-label="Message actions">
          <MessageCopy>
            <KindToolbarButton aria-label="Copy" />
          </MessageCopy>
        </KindToolbar>
        <Feedback
          commentSent={commentSent}
          onComment={() =>
            new Promise<void>((resolve) => {
              setTimeout(() => {
                setCommentSent(true);
                resolve();
              }, 600);
            })
          }
        />
      </MessageToolbar>
    </Message>
  );
}
```
</Example>

## Installation [#installation]

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

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

## Composition [#composition]

```text
Feedback
├── FeedbackThumbs
│   ├── FeedbackUp
│   └── FeedbackDown
├── FeedbackComment
├── FeedbackThanks
└── FeedbackContent
    ├── FeedbackTitle
    ├── FeedbackCommentText
    ├── FeedbackCommentStatus
    ├── FeedbackCommentError
    └── FeedbackCommentSend
```

`Feedback` renders these parts when you pass no children: a group named by its `label`. `FeedbackThumbs` holds UI SDK's Toggle group, and `FeedbackUp` and `FeedbackDown` are its toggles, named **Good response** and **Bad response**. `FeedbackComment` is the **Add a comment** button and `FeedbackThanks` the text that replaces it. `FeedbackContent` is the popover: `FeedbackTitle` names it, `FeedbackCommentText` is UI SDK's Textarea, and `FeedbackCommentSend` sends the text, with `FeedbackCommentStatus` or `FeedbackCommentError` beside it.

## Usage [#usage]

### Rating [#rating]

Pressing a thumb presses it and unpresses the other, and pressing the pressed thumb again clears the rating. The thumbs are one Tab stop: the arrow keys move between them, and Enter or Space presses the focused one. `onRatingChange` gets `"up"`, `"down"` or `null`, with `details.reason` set to `"item-press"`.

Pass `defaultRating` to start with a rating, or `rating` with `onRatingChange` to control it. Call `details.cancel()` in `onRatingChange` to keep the rating as it was.

```tsx
const [rating, setRating] = useState<FeedbackRating>(null);

<Feedback rating={rating} onRatingChange={(next) => setRating(next)} />
```

### Comments [#comments]

Pass `onComment` to offer a comment. **Add a comment** appears beside the thumbs once one is pressed, without moving them, and leaves when the rating is cleared. Pressing it opens the box with focus in the text. A rating alone never opens it.

**Send** calls `onComment` with the text, trimmed, and stays disabled while the text is empty. Return a promise to hold the box open while it settles: Send stays disabled with a running mark and "Sending" beside it, so a second press calls you once. When it resolves, the box closes, empties and returns focus to **Add a comment**, and "Comment sent" is announced. When it rejects, the text stays with "Comment not sent. Try again." beside Send, and "Comment not sent" is announced.

Once you have the comment, pass `commentSent`: "Thanks for your feedback" takes the button's place at its height, and focus moves to it if the button had it.

```tsx
const [commentSent, setCommentSent] = useState(false);

<Feedback
  commentSent={commentSent}
  onComment={async (text) => {
    await saveComment(text);
    setCommentSent(true);
  }}
/>
```

Escape or a press outside closes the box and keeps what was written for the next time it opens. Pass `open` and `onOpenChange` to control the box, or `defaultOpen` to start with it open; `onOpenChange` gets UI SDK Popover's reason, like `trigger-press` or `escape-key`.

### Motion [#motion]

The box rises and fades in, and **Add a comment** and the thanks fade in when they appear. Under `prefers-reduced-motion`, or with `motion="reduced"`, the box only fades, over 120 ms, and with `motion="none"` nothing animates.

## API Reference [#api-reference]

### FeedbackOptions

| Prop              | Type                                                                                                  | Description                                                                                                                                                                                   |
| ----------------- | ----------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rating?`         | `FeedbackRating \| undefined`                                                                         | The rating. Passing it controls it: change it in `onRatingChange`.                                                                                                                            |
| `defaultRating?`  | `FeedbackRating \| undefined`                                                                         | The rating at first, when `rating` isn't passed. Default: `null`                                                                                                                              |
| `onRatingChange?` | `((rating: FeedbackRating, details: ChangeDetails<FeedbackRatingChangeReason>) => void) \| undefined` | Called when a person or `rate` changes the rating, with why. Pressing the pressed thumb clears it.                                                                                            |
| `onComment?`      | `FeedbackCommentCallback \| undefined`                                                                | Called with a comment. While set, "Add a comment" shows once there's a rating and opens a box to write one.                                                                                   |
| `commentSent?`    | `boolean \| undefined`                                                                                | Whether the host has the comment: "Thanks for your feedback" replaces "Add a comment". Default: `false`                                                                                       |
| `label?`          | `string \| undefined`                                                                                 | Names the feedback. Default: `"Feedback"`                                                                                                                                                     |
| `open?`           | `boolean \| undefined`                                                                                | Whether the comment box is open. Passing it controls it: change it in `onOpenChange`.                                                                                                         |
| `defaultOpen?`    | `boolean \| undefined`                                                                                | Whether the comment box is open at first, when `open` isn't passed. Default: `false`                                                                                                          |
| `onOpenChange?`   | `((open: boolean, details: ChangeDetails<PopoverOpenChangeReason>) => void) \| undefined`             | Called when the comment box opens or closes, with what caused it.                                                                                                                             |
| `motion?`         | `"auto" \| "none" \| "reduced"`                                                                       | How the comment box opens and "Add a comment" and the thanks appear: at full motion the box rises in; reduced motion only fades. `"auto"` follows `prefers-reduced-motion`. Default: `"auto"` |

### Agent [#agent]

An agent connected with `createAgent` finds the feedback by its label and reads its `rating`. `rate("up")`, `rate("down")` or `rate(null)` changes it as a press does, reporting `details.source` as `"agent"` to `onRatingChange`. `submitComment(text)` fills the box and sends it through `onComment`, offered while **Add a comment** shows and no comment is being sent. Neither asks a person first; require one through `createAgent`'s `allow` if your `onComment` posts somewhere public. Like any component with a button, it also has UI SDK's generic `press`.

### FeedbackAgentActions

| Prop            | Type                                        | Description                                                                                                                                                                                                                                                                                |
| --------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `rate`          | `(rating: FeedbackRating) => boolean`       | Rates the response, or clears the rating with `null`, as a press does. Returns whether the change was accepted.                                                                                                                                                                            |
| `submitComment` | `((text?: string) => boolean) \| undefined` | Sends `text`, which also fills the comment box, else the box's text, through `onComment`. Offered only while "Add a comment" shows and no comment is being sent. Returns whether it sent anything: blank text, or a call while one is pending, sends nothing and leaves the box as it was. |

<Caption>
Runs in React and Web Components. On `<kind-feedback>`, props are kebab-case attributes, `rating` and `defaultRating` are properties only, and `open` is a property too; `onRatingChange` is the `ratingchange` event and `onOpenChange` the `openchange` event. The `can-comment` attribute offers a comment, and Send fires `comment` with the text as `detail.value`: call `event.detail.waitUntil(promise)` to hold the box open. The element fills in its parts when it has no children.
</Caption>