Description

PromptSuggestion is the set of starter prompts shown before a conversation begins. It is a compound component: the root renders a <div> and picks the layout, Header holds a page-level Title and Description, Group adds a labelled <section>, Items lays suggestions out on a responsive grid, and each Item is a registry Button so hover, press, focus and disabled states come for free.

Use it on the empty state of a chat thread, the landing screen of a copilot panel, or a template picker where each card starts a new conversation. layout="pill" fits short one-line prompts under a greeting. layout="card" fits named templates with a description, tags and a footer.

Don't use it for replies inside a running conversation or for actions on a single message; that is Chat Message Actions. For a menu of commands, use Dropdown Menu or Command. If the options are filters that stay selected, use Chip or Segmented Control, since a suggestion is a one-shot action.

PromptSuggestion is a Create UI Pro component. Install it with a Pro seat.

Installation

pnpm dlx @create-ui/cli add prompt-suggestion

Anatomy

<PromptSuggestion>
  <PromptSuggestion.Header>
    <PromptSuggestion.Title />
    <PromptSuggestion.Description />
  </PromptSuggestion.Header>
  <PromptSuggestion.Group>
    <PromptSuggestion.Items>
      <PromptSuggestion.Item>
        <PromptSuggestion.ItemTitle />
        <PromptSuggestion.ItemDescription />
        <PromptSuggestion.ItemTags />
        <PromptSuggestion.ItemFooter>
          <PromptSuggestion.ItemMeta />
        </PromptSuggestion.ItemFooter>
      </PromptSuggestion.Item>
    </PromptSuggestion.Items>
  </PromptSuggestion.Group>
</PromptSuggestion>

Usage

import { PromptSuggestion } from "@/components/ui/prompt-suggestion"

<PromptSuggestion>
  <PromptSuggestion.Items>
    <PromptSuggestion.Item onClick={() => setValue("Summarize this thread")}>
      Summarize this thread
    </PromptSuggestion.Item>
  </PromptSuggestion.Items>
</PromptSuggestion>

Examples

Every example is a Pro preview (marked with a Pro badge).

Card layout

layout="card" turns each item into a stacked tile with ItemTitle and ItemDescription. The grid goes one, two, then three columns wide, and every card in a row stretches to the tallest one.

Appearance

Item forwards Button's appearance. outline is the default and reads well on a plain page, soft gives each suggestion a fill, and ghost drops the border for dense side panels.

With icon

Put a glyph straight into a pill item, before the text. The label is a flex row with a small gap, and svgs are sized to 16px, so no wrapper is needed.

Card details

ItemTags turns each string child into a neutral Badge (arrays and Fragments are flattened, elements pass through). ItemFooter is pushed to the bottom of the card, which keeps ItemMeta aligned across a row of uneven descriptions.

Groups

Group adds a <section> with a label and optional description. The label renders an <h3> by default; set headingLevel to fit your page outline, and use Title asChild when the title needs to be the page <h1>.

As link

With asChild, the item renders your <a> instead of a <button>. Use it when a suggestion opens a new chat URL rather than filling the composer on the same page.

With Prompt Input

The usual wiring: clicking a suggestion writes it into a controlled PromptInput and moves focus to the textarea, so the user can edit before sending. The suggestions give way to the thread once a message goes out.

Accessibility

Every item is a native <button> (or your own <a> with asChild), so each suggestion is its own tab stop and responds to the platform keys.

ARIA notes:

• The component adds no roles. Title is an <h2>, a Group label is an <h3>, and both can change level through asChild and headingLevel.
• A card item's accessible name is all of its text: title, description, tags and meta. Keep card copy short, or set aria-label on the item when the extra text makes the name noisy.
• The pill chevron is decorative and marked aria-hidden.
• disabled sets the native attribute on a button. With asChild, Button sets aria-disabled and removes the link from the tab order instead.
• Focus is drawn with Button's outline, not a ring, and the chevron reveal and press transitions are dropped under prefers-reduced-motion.

Styling

Tailwind override: pass className to any part. Items is a CSS grid, so column counts are changed there.

<PromptSuggestion.Items className="sm:grid-cols-1">
  {/* items */}
</PromptSuggestion.Items>

Data slots and attributes: the component sets these for CSS targeting:

• data-slot="prompt-suggestion" on the root, with data-layout ("pill" or "card").
• data-slot="prompt-suggestion-header", -title and -description on the header parts.
• data-slot="prompt-suggestion-group" on the group <section>, with -group-header, -group-label and -group-description inside it.
• data-slot="prompt-suggestion-items" on the grid, with data-layout.
• data-slot="prompt-suggestion-item" on each item, with data-layout plus Button's data-variant, data-appearance and data-size.
• data-slot="button-label" on the content wrapper inside each item.
• data-slot="prompt-suggestion-item-end-icon" on the pill chevron.
• data-slot="prompt-suggestion-item-title", -item-description, -item-meta, -item-tags and -item-footer on the card parts.
• data-slot="badge" on each tag generated by ItemTags.

[data-slot="prompt-suggestion-item"][data-layout="card"]:hover
  [data-slot="prompt-suggestion-item-title"] {
  /* ... */
}

Related Components

• Prompt Input: the composer a suggestion usually fills.
• Chat Message Actions: use it for copy, retry and feedback actions on a message that already exists.
• Chip: use it for filters or options that stay selected, not one-shot prompts.
• Button: use it for a single call to action instead of a set of starter prompts.

API Reference

PromptSuggestion

The root. Extends React.ComponentProps<"div"> and shares layout with every part through context.

Props

Variants

PromptSuggestion.Root is the same component.

PromptSuggestion.Header

Stacks the title and description. Extends React.ComponentProps<"div">.

Props

PromptSuggestion.Title

The heading above the suggestions. Renders an <h2> and extends React.ComponentProps<"h2">.

Props

PromptSuggestion.Description

Supporting copy under the title, capped at a 640px measure. Renders a <p> and extends React.ComponentProps<"p">.

Props

PromptSuggestion.Group

A labelled set of suggestions. Renders a <section> and extends React.ComponentProps<"section">.

Props

PromptSuggestion.Items

The responsive grid. Extends React.ComponentProps<"div"> and reads layout from the root: pills go two up from sm, cards go two up from sm and three up from lg.

Props

PromptSuggestion.Item

One suggestion. Wraps the registry Button, so it accepts every Button prop except size, shape and iconOnly, which the layout controls. That includes onClick, disabled, loading and any native button attribute.

Props

Variants

PromptSuggestion.ItemTitle / ItemDescription / ItemMeta

The card's title, body copy and small secondary text. Each renders a <span> and extends React.ComponentProps<"span">, so they are valid inside a <button>.

Props

PromptSuggestion.ItemTags

A wrapping row of tags. Renders a <span> and extends React.ComponentProps<"span">. Each string or number child becomes one Badge (variant="neutral", appearance="soft", size="sm"); arrays and Fragments are flattened first, whitespace-only text is skipped, and elements such as your own Badge pass through untouched.

Props

PromptSuggestion.ItemFooter

A row pinned to the bottom of a card with mt-auto, spacing its children apart. Renders a <span> and extends React.ComponentProps<"span">.

Props

Every part is also exported by name (PromptSuggestionHeader, PromptSuggestionItem, and so on), along with the promptSuggestionItemsVariants and promptSuggestionItemVariants CVA recipes.

Types

type PromptSuggestionLayout = "pill" | "card"
type PromptSuggestionHeadingLevel = 2 | 3 | 4 | 5 | 6