# Prompt suggestions

Prompts to start from. Choosing one puts it in the composer to edit, rather than sending it, because suggestions are model output too. Loading shows placeholders of the right shape; an empty list renders nothing.

- Registry name: `prompt-suggestions` (`@candor/prompt-suggestions`)
- Tier: Free (MIT). No licence key needed.
- Docs: https://candor.themethodic.com/docs/prompt-suggestions

## Install

```bash
npx candor-ui add prompt-suggestions
```

Run `npx candor-ui@latest init` once first (https://candor.themethodic.com/get-started.md). Without the CLI: `npx shadcn@latest add @candor/prompt-suggestions`.
It brings in: chat, locale, skeleton, utils.
npm packages: lucide-react@^1.67.0.

## Example

```tsx
"use client"

import * as React from "react"
import { PromptSuggestions } from "@/components/prompt-suggestions"

export default function Example() {
  const [chosen, setChosen] = React.useState("")
  return (
    <div className="flex max-w-lg flex-col gap-3">
      <PromptSuggestions
        suggestions={[
          { id: "1", text: "Which orders are late this week?" },
          { id: "2", text: "Draft a reply to the newest complaint" },
          { id: "3", text: "Summarise yesterday’s refunds" },
        ]}
        onChoose={(s) => setChosen(s.text)}
      />
      {chosen && <p className="text-xs text-muted-foreground">Put in the composer to edit: “{chosen}”</p>}
    </div>
  )
}
```

## <PromptSuggestions>

Props:

- `suggestions: PromptSuggestion[]`: What to offer.
- `onChoose: (suggestion: PromptSuggestion) => void`: Called with the chosen one; put it in the composer to edit rather than sending it.
- `label?: string | undefined`: The heading above the suggestions; "Try asking" by default.
- `loading?: boolean | undefined` (default `false`): Shows placeholders while suggestions load.
- `variant?: "chips" | "cards" | undefined` (default `"chips"`): Compact chips, or larger cards for an empty thread.
- `className?: string | undefined`

## Strings (`promptSuggestions`)

The fixed words, English by default. Override any of them under `promptSuggestions` in `<LocaleProvider strings={{ promptSuggestions: { … } }}>`; the table is exported as `promptSuggestionsStrings`.

- `label`: Try asking

## Rules for using Candor UI

- Components take plain typed data. Never pass model output as HTML or render it as a link; messages are typed blocks.
- A control that can't be used says why: wrap it in `<Locked reason="…">`, don't just disable it.
- Don't show a value you don't have: leave it out (it renders as —) rather than guess. An estimate is labelled as one.
- Nothing is pre-selected in a decision a person makes, and the agent is named from your app's data, never from model output.
- Your app's words go in `LocaleProvider` (fixed strings) and `TermsProvider` (nouns); entity kinds and agent roles in `EntityKindsProvider` and `AgentRolesProvider`.