# Suggestion (/docs/agent-ui/components/suggestion)

Use suggestions under an answer or an empty composer, to offer the next things a person might ask. Each one is a short chip, and the row scrolls sideways when they don't all fit.

<Example caption="Press a suggestion to send it. Press Next to bring the later ones into view, or swipe the row.">
<Basic />

```tsx
"use client";
import { useState } from "react";
import { Suggestion } from "@/components/ui/suggestion";

const suggestions = [
  { id: "summarize", label: "Summarize this thread" },
  { id: "reply", label: "Draft a reply", description: "Short and friendly" },
  { id: "questions", label: "List the open questions" },
  { id: "issues", label: "Find related issues" },
  { id: "tests", label: "Suggest a test plan" },
];

export default function SuggestionExample() {
  const [prompt, setPrompt] = useState<string>();
  return (
    <div className="flex w-full max-w-md flex-col gap-3">
      <Suggestion
        suggestions={suggestions}
        onPick={(id) => setPrompt(suggestions.find((suggestion) => suggestion.id === id)?.label)}
      />
      <p className="text-sm text-[var(--kind-color-muted)]">
        {prompt ? `Sent: ${prompt}` : "Nothing sent yet."}
      </p>
    </div>
  );
}
```
</Example>

## Installation [#installation]

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

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

## Composition [#composition]

```text
Suggestion
├── SuggestionViewport
│   └── SuggestionItem
└── SuggestionControls
    ├── SuggestionPrevious
    └── SuggestionNext
```

`Suggestion` is a group named by its `label` that holds UI SDK's Carousel. `SuggestionViewport` is the row that scrolls, each `SuggestionItem` is a button showing a suggestion's `label` and `description`, and `SuggestionPrevious` and `SuggestionNext` scroll the row. `SuggestionControls` holds them and hides them while every suggestion fits.

## Usage [#usage]

### Picking [#picking]

Pass `suggestions`, each with an `id`, a `label` and an optional `description`, and `onPick`, which gets the `id` of the one chosen. Sending it is up to you: put the text in the composer, or send it straight away.

```tsx
<Suggestion
  suggestions={[{ id: "summarize", label: "Summarize this thread" }]}
  onPick={(id) => send(prompts[id])}
/>
```

`onPick` gets the reason `item-press` when a person pressed it, or `imperative` from `pick`. Without `onPick`, the suggestions show but can't be chosen.

### Overflow [#overflow]

The suggestions sit in one row. When they don't all fit, **Previous** and **Next** appear after it and the edge with more past it fades; while they fit, the buttons take no room. Only suggestions at least half in view can be reached with Tab, so press **Next**, swipe or scroll to reach the rest.

### Keyboard [#keyboard]

Tab moves through the suggestions in view, then **Previous** and **Next**. Enter or Space picks the focused one.

### Motion [#motion]

A suggestion added after the row first shows fades up once; one you update or that was there from the start doesn't. A removed one leaves at once, and if it had focus, focus moves to the next suggestion. Under `prefers-reduced-motion`, or with `motion="reduced"`, new ones only fade and a press doesn't shrink the chip. With `motion="none"`, neither animates. Scrolling to another page follows `prefers-reduced-motion` only.

## API Reference [#api-reference]

### SuggestionOptions

| Prop           | Type                                                                                | Description                                                                                                                                                                  |
| -------------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `suggestions?` | `SuggestionItem[] \| undefined`                                                     | The suggestions, in the order they show. Default: `[]`                                                                                                                       |
| `onPick?`      | `((id: string, details: ChangeDetails<SuggestionPickReason>) => void) \| undefined` | Called with a suggestion's `id` when a person or `pick` chooses it. Without it the suggestions can't be chosen.                                                              |
| `label?`       | `string \| undefined`                                                               | Names the row of suggestions. Default: `"Suggestions"`                                                                                                                       |
| `motion?`      | `"auto" \| "none" \| "reduced"`                                                     | How suggestions added after the first frame come in: they fade up at full motion and fade under reduced motion. `"auto"` follows `prefers-reduced-motion`. Default: `"auto"` |

### Agent [#agent]

An agent connected with `createAgent` finds the row by its label and reads every suggestion, wherever the row has scrolled. Its `pick` takes a suggestion's `id` or its label, the same as a person pressing it, and refuses one that isn't listed. It's offered only while `onPick` is set.

### SuggestionAgentActions

| Prop   | Type                                     | Description                                                                                                                                          |
| ------ | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pick` | `((id: string) => boolean) \| undefined` | Chooses a suggestion by its `id`, as a press would. Returns `false` for an unknown one or when the host cancels. Offered only while `onPick` is set. |

`pick` doesn't wait for a person to confirm. When a pick sends a prompt, you can ask the person first by returning their answer from your `allow`, which also answers every action that does need a person:

```ts
import { createAgent } from "@ui-sdk/react/agent";

const agent = createAgent({
  allow: ({ component, confirm }) => {
    if (confirm) return window.confirm(confirm);
    if (component === "kind-suggestion") return window.confirm("Let the agent send a suggested prompt?");
    return true;
  },
});
```

<Caption>
Runs in React and Web Components. On `<kind-suggestion>`, set `suggestions` as a property, and `label` and `motion` as attributes. Picking needs the `can-pick` attribute and fires `pick`, with the suggestion's `id` as `event.detail.value`. The element fills in its row when it has no children.
</Caption>