# Suggestion

Prompts a person can send with one press, in a row that scrolls or wraps.

Source: [suggestion.tsx](https://github.com/jakejarvis/jarvis-ui/blob/main/src/components/ui/suggestion.tsx)

```tsx
"use client";

import * as React from "react";

import { Suggestion, SuggestionGroup } from "@/components/ui/suggestion";

const prompts = [
  "Summarize this week’s incidents",
  "Which deploys failed?",
  "Draft a status update",
  "Compare latency to last month",
];

export default function SuggestionPrompts() {
  const [sent, setSent] = React.useState<string>();

  return (
    <div className="flex w-full max-w-md flex-col gap-3">
      <SuggestionGroup>
        {prompts.map((prompt) => (
          <Suggestion key={prompt} value={prompt} onSelect={setSent} />
        ))}
      </SuggestionGroup>
      <p className="text-sm text-muted-foreground">{sent ? `Sent “${sent}”` : "Pick a prompt."}</p>
    </div>
  );
}
```

## Installation

Add the registry, once per project:

```bash
npx shadcn@latest registry add @jarvis=https://ui.jarv.is/r/{name}.json
```

Then add the component:

```bash
npx shadcn@latest add @jarvis/suggestion
```

## Usage

```tsx
"use client";

import { Suggestion, SuggestionGroup } from "@/components/ui/suggestion";

export function StarterPrompts({ onSend }: { onSend: (text: string) => void }) {
  return (
    <SuggestionGroup>
      <Suggestion value="What can you do?" onSelect={onSend} />
      <Suggestion value="Summarize my week" onSelect={onSend} />
    </SuggestionGroup>
  );
}
```

`onSelect` receives the suggestion's `value`, which is also its label unless you pass children.
Return a promise from `onSelect` to keep the suggestion pending until the promise settles. Your own
`onClick` runs first, and calling `event.preventDefault()` in it skips `onSelect`. When a row of
suggestions doesn't fit, it scrolls horizontally and fades at the edges where there's more to
scroll.

## Composition

- `SuggestionGroup`
  - `Suggestion`

## Examples

### Wrapped

`wrap` wraps the suggestions onto as many lines as they need.

```tsx
import { Suggestion, SuggestionGroup } from "@/components/ui/suggestion";

const prompts = [
  "Summarize this week’s incidents",
  "Which deploys failed?",
  "Draft a status update",
  "Compare latency to last month",
];

export default function SuggestionWrapped() {
  return (
    <SuggestionGroup wrap className="max-w-sm">
      {prompts.map((prompt) => (
        <Suggestion key={prompt} value={prompt} />
      ))}
    </SuggestionGroup>
  );
}
```

## Props

| Part | Extends |
| --- | --- |
| `SuggestionGroup` | `<div>` |
| `Suggestion` | [`Button`](https://ui.jarv.is/components/button.md) |

Base UI's [styling](https://base-ui.com/react/handbook/styling) and [composition](https://base-ui.com/react/handbook/composition) guides say more about `className`, `style` and `render`.

### SuggestionGroup

| Prop         | Type                                                     | Default | Description                                                                                                                                                                               |
| ------------ | -------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `wrap?`      | `boolean`                                                | `false` | Wraps the suggestions onto more lines, rather than scrolling them sideways on one.                                                                                                        |
| `className?` | `string`                                                 | —       | CSS class applied to the element.                                                                                                                                                         |
| `style?`     | `React.CSSProperties`                                    | —       | Style applied to the element.                                                                                                                                                             |
| `render?`    | `ComponentRenderFn<HTMLProps, {}> \| React.ReactElement` | —       | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |

### Suggestion

| Prop                     | Type                                                                                 | Default       | Description                                                                                                                                                                                                            |
| ------------------------ | ------------------------------------------------------------------------------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `nativeButton?`          | `boolean`                                                                            | `true`        | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`).                                      |
| `focusableWhenDisabled?` | `boolean`                                                                            | `false`       | Whether the button should be focusable when disabled.                                                                                                                                                                  |
| `variant?`               | `"destructive" \| "ghost" \| "link" \| "outline" \| "primary" \| "secondary"`        | `"secondary"` |                                                                                                                                                                                                                        |
| `size?`                  | `"default" \| "icon" \| "icon-lg" \| "icon-sm" \| "icon-xs" \| "lg" \| "sm" \| "xs"` | `"sm"`        |                                                                                                                                                                                                                        |
| `value`                  | `string`                                                                             | —             | The prompt the suggestion sends, and its label when it has no children.                                                                                                                                                |
| `onSelect?`              | `((value: string, event: React.MouseEvent<HTMLButtonElement>) => unknown)`           | —             | Called with `value` when the suggestion is pressed, unless `onClick` calls `event.preventDefault()`. Return a promise to keep the suggestion pending, and the others in its group disabled, until the promise settles. |
| `pendingAnnouncement?`   | `string`                                                                             | `"Loading"`   | What screen readers announce when the promise from `onSelect` hasn't settled after a second. Pass an empty string to announce nothing.                                                                                 |
| `className?`             | `string \| ((state: ButtonState) => string \| undefined)`                            | —             | CSS class applied to the element, or a function that returns a class based on the component's state.                                                                                                                   |
| `style?`                 | `React.CSSProperties \| ((state: ButtonState) => React.CSSProperties \| undefined)`  | —             | Style applied to the element, or a function that returns a style object based on the component's state.                                                                                                                |
| `render?`                | `ComponentRenderFn<HTMLProps, ButtonState> \| React.ReactElement`                    | —             | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.                              |
