Autocomplete

A searchable dropdown component that allows users to filter and select from a list of options.

Import#

import { Autocomplete } from "asheeui";

Usage#

"use client";

import { useState } from "react";
import { Autocomplete } from "asheeui";

const fruits = [
	{ label: "Apple", value: "apple" },
	{ label: "Banana", value: "banana" },
	{ label: "Cherry", value: "cherry" },
	{ label: "Date", value: "date" },
	{ label: "Elderberry", value: "elderberry" },
];

export default function Basic() {
	const [value, setValue] = useState<string | number>("");

	return (
		<Autocomplete
			value={value}
			onValueChange={setValue}
			options={fruits}
			placeholder="Search for a fruit..."
		/>
	);
}

Examples#

With custom input handling#

Allow custom values#

Menu styling#

With below list content#

Controlled with selected option#

Inheritance#

Autocomplete extends the <Input /> component and inherits all of its props and functionality. This means you can use any Input prop with Autocomplete, including:

• size, radius, variant, color
• label, labelAlign, description, message
• status, required, isLoading, disabled
• startContent, className, and all native input attributes

What Autocomplete adds#

Autocomplete extends Input with the following additional features:

What Autocomplete modifies#

Props#

Excluded Props#

The following Input props are not available on Autocomplete:

SelectMenuOption#

Menu Configuration#

The dropdown menu appearance is controlled through the menu prop, which accepts all MenuConfig options:

* Falls back through Global Configuration if not set. See below.

Global Configuration#

Autocomplete reads defaults from four places, in this order of precedence:

1. Instance prop: set directly on <Autocomplete />
2. Component config: components.autocomplete in your ashee.config
3. Theme default: defaultVariant / defaultRadius / defaultColor in your ashee.config
4. Built-in fallback: component's internal default values

Component config#

// ashee.config.ts
import type { ExternalConfig } from "asheeui";

export const config: ExternalConfig = {
  components: {
    autocomplete: {
      size: "md",
      radius: "md",
      variant: "bordered",
      color: "primary",
      labelAlign: "left",
      menu: {
        itemVariant: "ghost",
        itemColor: "primary",
        activeItemVariant: "faded",
        activeItemColor: "primary",
        radius: "md",
        size: "md",
        portal: true,
        lockScroll: false,
      },
    },
  },
};

Built-in fallbacks#

{
  size: "md",
  radius: "md",
  variant: "bordered",
  color: "primary",
  labelAlign: "left",
  menu: {
    itemVariant: "ghost",
    itemColor: "primary",
    activeItemVariant: "faded",
    activeItemColor: "primary",
    radius: "md",
    size: "md",
    portal: true,
    lockScroll: false,
  },
}

Accessibility#

• Renders with proper ARIA roles (combobox, listbox)
• Uses aria-expanded and aria-autocomplete for state indication
• Supports keyboard navigation and selection
• disabled items are not focusable or selectable
• Implements focus-visible indicators
• Uses Floating UI for robust positioning

Portal Behavior#

The Autocomplete dropdown menu is rendered in a React portal by default. This means the menu is attached to document.body rather than staying in the component's DOM hierarchy.

Why use a portal?#

• Escapes CSS containment: The menu appears above other content even when inside containers with overflow: hidden or contain: layout
• Avoids stacking context issues: The menu maintains proper z-index regardless of parent stacking contexts
• Works with any parent: The menu functions correctly regardless of where the Autocomplete is placed in the component tree
• Prevents clipping: The menu is never clipped by parent containers

When to disable the portal#

You may want to disable the portal (by setting menu.portal={false}) when:

• You need the menu to stay within a specific container for testing purposes
• You are rendering inside a shadow DOM or iframe where document.body is not appropriate
• You have specific layout requirements that depend on the menu remaining in the DOM hierarchy

You can also provide a custom menu.portalTarget to render the menu into a specific container instead of document.body.

Notes#

• Controlled Usage: Use value/onValueChange for controlled behavior.
• Custom Values: When allowCustomValue is enabled, ensure your application handles string values appropriately.
• Filtering: Options are filtered in real-time, case-insensitive, matching against option labels.
• Performance: For large option lists (1000+ items), consider implementing virtual scrolling or server-side filtering.
• Keyboard Navigation: Up/Down arrows navigate options, Enter selects, Escape closes.
• Portal: The dropdown menu is portaled to document.body by default. This can be disabled via the menu.portal prop or component config.
• Menu Configuration: All menu appearance options are consolidated into the menu prop for cleaner API surface.
• Inheritance: Autocomplete inherits all Input props except onChange and children.