Form Components

Autocomplete

Searchable combobox with keyboard navigation, type-to-filter, and optional multi-select. Supports icons, descriptions, avatars, loading state, helper text, and error state.

Quick Preview

Preferred framework

Selected: react

Installation

// Copy from
src/components/forms/Autocomplete.tsx

Usage

'use client'
import { useState } from 'react'
import { Autocomplete } from '@/components/forms/Autocomplete'

// Single-select (controlled)
export function FrameworkPicker() {
  const [framework, setFramework] = useState<string | undefined>()

  return (
    <Autocomplete
      options={[
        { value: 'react', label: 'React',   icon: '⚛️'  },
        { value: 'vue',   label: 'Vue',     icon: '💚'  },
        { value: 'next',  label: 'Next.js', icon: '▲'   },
      ]}
      value={framework}
      label="Framework"
      helperText="Select your preferred framework"
      onChange={(v) => setFramework(v as string | undefined)}
    />
  )
}

// Multi-select with max limit
export function SkillsPicker() {
  const [skills, setSkills] = useState<string[]>([])

  return (
    <Autocomplete
      multiple
      maxItems={5}
      options={SKILLS_OPTIONS}
      value={skills}
      label="Skills (max 5)"
      placeholder="Add skill…"
      onChange={(v) => setSkills(v as string[])}
    />
  )
}

Examples

Single select

Default mode — pick one option.

Framework

selected: react

Multi-select

Pass multiple to pick many options. Selected items appear as chips inside the input.

Frameworks

⚛️React▲Next.js

selected: [react, next]

With icons and descriptions

Add icon and description to each option.

Languages

🔷TypeScript

Loading state

Show a spinner while async results load.

Framework (async)

With helper text

Provide contextual hint below the input.

Framework

Choose the framework for your project

With error state

Display validation error below input.

Framework

This field is required

Disabled

Pass disabled to prevent interaction.

Framework

Prompt Preview

Copy a prompt that recreates this UI

Paste this into your AI coding assistant to generate code that closely matches the reference, including color, size, shape, typography, spacing, and polish.

Copy-ready AI prompt

Starts from the current visual reference and project constraints.

Build a forms component named Autocomplete in React/Next.js.
Goal: recreate the same overall UI and behavior as the Autocomplete reference from a component gallery.
What it needs to communicate: Searchable combobox with keyboard navigation, type-to-filter, and optional multi-select. Supports icons, descriptions, avatars, loading state, helper text, and error state..

Project constraints:
- Use Next.js 16.2.6 with the App Router, React 19, TypeScript strict mode, and Tailwind CSS v4.
- Do not create a tailwind.config.js file. Use Tailwind v4 utilities and CSS variables where design tokens are needed.
- If you are implementing this inside the same project, use the Prompt font via next/font/google. If not, use the closest equivalent typeface.
- Return production-ready code with imports, responsive behavior, keyboard accessibility, and polished empty, hover, focus, active, and disabled states where relevant.
- Match the reference closely: color palette, spacing scale, border radius, shadows, icon scale, typography hierarchy, and motion timing.

Component-specific expectations:
- Support label, helper, error, disabled, and validation states.
- Ensure keyboard usability and accessible form semantics.
- Avoid unnecessary dependencies unless the behavior truly requires them.
- No explicit color literals were found in the examples. Match the live reference and the project accent color when appropriate.

Props to support:
- options: AutocompleteOption[] — required — Array of selectable options
- value: string | string[] — Controlled selected value(s)
- defaultValue: string | string[] — Uncontrolled default value(s)
- multiple: boolean — default false — Enable multi-selection; selected items render as chips
- placeholder: string — default 'Search…' — Input placeholder text
- label: string — Label displayed above the input
- helperText: string — Helper text shown below the input
- errorText: string — Error message; overrides helperText and adds red ring
- disabled: boolean — default false — Disables all interaction
- loading: boolean — default false — Replaces chevron with spinner
- clearable: boolean — default true — Show × button to clear selection
- maxItems: number — Limit selected items in multi mode
- noOptionsText: string — default 'No options found' — Empty-state label
- onChange: (value: string | string[] | undefined) => void — Fires when selection changes
- onSearch: (query: string) => void — Fires on each keystroke — use for async data fetching

Reference usage patterns:
- No examples were documented. Infer a sensible default presentation and one richer usage example.

Feature expectations:
- Keyboard navigation (↑↓ Enter Escape Backspace)
- Type-to-filter
- Multi-select with chip tokens
- Icon, description, and avatar per option
- Loading spinner for async search
- Helper text and error state
- Accessible combobox (ARIA)

Output requirements:
- Return complete code, not pseudocode.
- Include all necessary imports and helper types.
- Keep the implementation accessible, responsive, and visually finished.
- Match the reference for color, size, shape, typography, spacing, and interaction states as closely as possible.
- If multiple files are needed, organize them cleanly and explain the file structure briefly.

Tweak only product-specific copy or data after the first generation pass.

Props

Prop	Type	Default	Description
`options`*	`AutocompleteOption[]`	-	Array of selectable options
`value`	`string \| string[]`	-	Controlled selected value(s)
`defaultValue`	`string \| string[]`	-	Uncontrolled default value(s)
`multiple`	`boolean`	`false`	Enable multi-selection; selected items render as chips
`placeholder`	`string`	`'Search…'`	Input placeholder text
`label`	`string`	-	Label displayed above the input
`helperText`	`string`	-	Helper text shown below the input
`errorText`	`string`	-	Error message; overrides helperText and adds red ring
`disabled`	`boolean`	`false`	Disables all interaction
`loading`	`boolean`	`false`	Replaces chevron with spinner
`clearable`	`boolean`	`true`	Show × button to clear selection
`maxItems`	`number`	-	Limit selected items in multi mode
`noOptionsText`	`string`	`'No options found'`	Empty-state label
`onChange`	`(value: string \| string[] \| undefined) => void`	-	Fires when selection changes
`onSearch`	`(query: string) => void`	-	Fires on each keystroke — use for async data fetching

Keyboard Navigation

Key	Action
`↓ / ↑`	Move focus through options
`Enter`	Select focused option
`Escape`	Close dropdown and blur input
`Backspace`	Remove last selected chip (multi mode, when input is empty)
`Tab`	Close dropdown and move focus to next element