> ## Documentation Index
> Fetch the complete documentation index at: https://anvil.servicetitan.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Suggestion - Web

> Suggestions offer quick follow-up actions or prompts.

> [!NOTE]
>
> For development, import `Suggestion` from
> `@servicetitan/anvil2-ai-kit`. For design, find it in the
> [AI Kit Web Component Library file](https://www.figma.com/design/QEIsArLktLeJAaFvcpw3PO/AI-Kit-Web-Component-Library).

ai-kit-suggestion

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/ai-kit-suggestion?file=src/App.tsx)

```tsx lines theme={null}
import { Suggestion } from "@servicetitan/anvil2-ai-kit";

function App() {
  return <Suggestion label="What can you help me with?" />;
}

export default App;
```

## Options

A single chip is one tappable follow-up; `SuggestionList` groups a capped set of chips (design caps at 3, \~40 characters each) beneath an agent response.

### List of Suggestions

ai-kit-suggestion-list

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/ai-kit-suggestion-list?file=src/App.tsx)

```tsx lines theme={null}
import { SuggestionList } from "@servicetitan/anvil2-ai-kit";

function App() {
  return (
    <SuggestionList
      suggestions={[
        "What can you help me with?",
        "Order more",
        "Show recent updates",
      ]}
      onSelect={() => {}}
    />
  );
}

export default App;
```

`SuggestionList` renders one chip per entry in `suggestions` and exposes the set to assistive tech as one labelled group — "Suggested replies" by default. Selecting a chip fires `onSelect` with that suggestion's text and index; clearing the list and inserting the text into the message input is the consumer's job.

### Disabled

ai-kit-suggestion-disabled

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/ai-kit-suggestion-disabled?file=src/App.tsx)

```tsx lines theme={null}
import { Suggestion } from "@servicetitan/anvil2-ai-kit";

function App() {
  return (
    <div style={{ display: "flex", gap: 8 }}>
      <Suggestion label="Order more" />
      <Suggestion label="Order more" isDisabled />
    </div>
  );
}

export default App;
```

`isDisabled` dims the chip and blocks press and hover, but keeps it focusable for keyboard users.

## Behavior

The chip responds to hover, press, and keyboard focus, and a list of chips wraps to fit its container.

### Visual States

ai-kit-suggestion-visual-states

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/ai-kit-suggestion-visual-states?file=src/App.tsx)

```tsx lines theme={null}
import { Suggestion } from "@servicetitan/anvil2-ai-kit";

function App() {
  return (
    <div style={{ display: "flex", gap: 8 }}>
      <Suggestion label="Default" />
      <Suggestion label="Hover" data-interactive="hover" />
      <Suggestion label="Pressed" data-interactive="active" />
      <Suggestion label="Focus" data-interactive="focus-visible" />
    </div>
  );
}

export default App;
```

Hover and press shift the surface fill and lift to match Card; keyboard focus adds a ring without changing the fill.

### Wrapping

ai-kit-suggestion-wrapping

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/ai-kit-suggestion-wrapping?file=src/App.tsx)

```tsx lines theme={null}
import { SuggestionList } from "@servicetitan/anvil2-ai-kit";

function App() {
  return (
    <div style={{ maxWidth: "20rem" }}>
      <SuggestionList
        suggestions={[
          "What can you help me with today?",
          "Summarize my most recent job activity",
          "Show me overdue invoices",
        ]}
        onSelect={() => {}}
      />
    </div>
  );
}

export default App;
```

`SuggestionList` wraps chips onto new lines once a row runs out of width, rather than overflowing or shrinking the chips.

## Usage Guidelines

### When to Use

Use the Suggestion or Suggestion List when:

* **One follow-up prompt** – A single tappable chip offers one quick follow-up action or prompt. Use the Suggestion.
* **Follow-ups beneath an agent response** – A small set of prompts sits under an agent response as one labelled group. Use the Suggestion List.

### When not to use

Avoid using the Suggestion or Suggestion List for:

* **Several separate chips** – Placing individual Suggestion chips side by side skips the shared group label and selection handling. Use the Suggestion List instead.
* **More than three prompts or long prompts** – The Suggestion List does not enforce content limits. Trim the set to three suggestions of about 40 characters each.

## Keyboard Interaction

Users can navigate and select a Suggestion using standard keyboard controls.

| Key | Description |
| - | - |
| Tab | Moves focus to the next chip |
| Enter / Space | Activates the focused chip |

## Code

**Implementation**

ai-kit-suggestion

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/ai-kit-suggestion?file=src/App.tsx)

```tsx lines expandable theme={null}
import { Suggestion } from "@servicetitan/anvil2-ai-kit";

function App() {
  return <Suggestion label="What can you help me with?" />;
}

export default App;
```

## Common Examples

To use a single `Suggestion`, pass a required `label` and handle selection with `onPress`. Supply the label already localized; the component renders it verbatim.

```tsx theme={null}
import { Suggestion } from "@servicetitan/anvil2-ai-kit";

function ExampleComponent() {
  return (
    <Suggestion
      label="Show overdue invoices"
      onPress={() => sendPrompt("Show overdue invoices")}
    />
  );
}
```

### Suggestion list

Use `SuggestionList` for a wrapping group of chips. Each string in `suggestions` becomes a `Suggestion`. `onSelect` receives the selected string and index.

ai-kit-suggestion-list

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/ai-kit-suggestion-list?file=src/App.tsx)

```tsx lines expandable theme={null}
import { SuggestionList } from "@servicetitan/anvil2-ai-kit";

function App() {
  return (
    <SuggestionList
      suggestions={[
        "What can you help me with?",
        "Order more",
        "Show recent updates",
      ]}
      onSelect={() => {}}
    />
  );
}

export default App;
```

The list does not enforce content limits. Keep the set to three suggestions of about 40 characters each.

### Wrapping

Suggestions wrap to new lines when the container runs out of space.

ai-kit-suggestion-wrapping

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/ai-kit-suggestion-wrapping?file=src/App.tsx)

```tsx lines expandable theme={null}
import { SuggestionList } from "@servicetitan/anvil2-ai-kit";

function App() {
  return (
    <div style={{ maxWidth: "20rem" }}>
      <SuggestionList
        suggestions={[
          "What can you help me with today?",
          "Summarize my most recent job activity",
          "Show me overdue invoices",
        ]}
        onSelect={() => {}}
      />
    </div>
  );
}

export default App;
```

### Disabled

Set `isDisabled` on a single `Suggestion` to block selection.

ai-kit-suggestion-disabled

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/ai-kit-suggestion-disabled?file=src/App.tsx)

```tsx lines expandable theme={null}
import { Suggestion } from "@servicetitan/anvil2-ai-kit";

function App() {
  return (
    <div style={{ display: "flex", gap: 8 }}>
      <Suggestion label="Order more" />
      <Suggestion label="Order more" isDisabled />
    </div>
  );
}

export default App;
```

## Internationalization

Suggestion labels are consumer content and must be localized before they are passed to the component. `SuggestionList` uses `ai-kit.suggestionList.label` for its default group name. Pass `aria-label` to override it, or mount `AiKitIntlProvider` inside `CartoTheme` to override the message globally.

```tsx theme={null}
<AiKitIntlProvider
  messages={{
    "ai-kit.suggestionList.label": "Suggested next steps",
  }}
>
  <SuggestionList
    suggestions={["Show overdue invoices"]}
    onSelect={sendPrompt}
  />
</AiKitIntlProvider>
```

## React Accessibility

* `Suggestion` uses its visible `label` as its accessible name.
* `SuggestionList` exposes its chips as one `role="group"` named by a localized label.
* Users activate a focused suggestion with Enter or Space.

**Suggestion Props**

```tsx theme={null}
<Suggestion
  label="Show overdue invoices"
  onPress={() => sendPrompt("Show overdue invoices")}
/>
```

## `Suggestion` Props

The `Suggestion` accepts the following props and forwards remaining React Aria `Button` props except `children`, `className`, `style`, and `isPending`.

**label** `string` *required*

Visible text and accessible name. Supply a short, localized follow-up
prompt.

**className** `string`

Class merged onto the chip.

**isDisabled** `boolean`

Disables selection.

**onPress** `(e: PressEvent) =\> void`

Handles selection for click, touch, and keyboard activation.

**SuggestionList Props**

```tsx theme={null}
<SuggestionList
  suggestions={["Show overdue invoices", "Summarize recent jobs"]}
  onSelect={(suggestion, index) => sendPrompt(suggestion)}
/>
```

## `SuggestionList` Props

The `SuggestionList` accepts the following props and forwards remaining `<div>` attributes except `children`, the DOM `onSelect` event, and `style`.

**onSelect** `(suggestion: string, index: number) =\> void` *required*

Called when a suggestion is selected. The consumer owns inserting the
text and dismissing the list.

**suggestions** `string[]` *required*

Suggestions to render in order. Each string is both the visible label and
the selection payload.

**aria-label** `string`

Accessible name for the suggestion group. When omitted, the component
uses the localized `ai-kit.suggestionList.label` message.

**className** `string`

Class merged onto the list container.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.