︲

︲

Autocomplete

An input that suggests options as you type.

Note: The Autocomplete is a fully custom component with no external dependencies — built as a self-contained JavaScript component exposed through a Python API for use in Reflex.

Installation

Copy the following code into your app directory.

uv

uv run buridan add component autocomplete
from components.ui.component import autocomplete

Anatomy

Use the following composition to build an Autocomplete component.

autocomplete( items=[...], )

Examples

Basic

A minimal autocomplete with a static list of items.

from components.ui.autocomplete import autocomplete


def autocomplete_basic():
    return autocomplete(
        items=["feature", "fix", "bug", "docs", "internal", "mobile"],
        placeholder="Search tags...",
    )

Selected Value

Wire up on_select_item to capture the selected value.

import reflex as rx

from components.ui.autocomplete import autocomplete


def autocomplete_select_value():
    return autocomplete(
        items=["feature", "fix", "bug", "docs", "internal", "mobile"],
        placeholder="Search and select...",
        on_select_item=lambda value: rx.toast(value),
    )

Grouped List

Pass a group key to your data structure to group items together.

from components.ui.autocomplete import autocomplete


def autocomplete_grouping():
    return autocomplete(
        items=[
            {"group": "Fruits", "items": ["Apple", "Banana", "Mango"]},
            {"group": "Vegetables", "items": ["Carrot", "Broccoli"]},
            {"group": "Grains", "items": ["Rice", "Wheat", "Oats"]},
        ],
        placeholder="Search tags...",
        separator_class="bg-transparent",
        popup_class="mt-2",
        root_class="scrollbar-none",
    )

Large List

Autocomplete works efficiently with large lists — filtering happens entirely in the browser.

from components.ui.autocomplete import autocomplete

ITEMS = [
    "feature",
    "fix",
    "bug",
    "docs",
    "internal",
    "mobile",
    "frontend",
    "backend",
    "performance",
    "accessibility",
    "design",
    "research",
    "testing",
    "infrastructure",
    "documentation",
    "component: accordion",
    "component: alert dialog",
    "component: autocomplete",
    "component: avatar",
    "component: badge",
    "component: breadcrumb",
    "component: button",
    "component: checkbox",
    "component: collapsible",
    "component: context menu",
    "component: dialog",
    "component: field",
    "component: input",
    "component: input group",
    "component: kbd",
    "component: menu",
    "component: popover",
    "component: scroll area",
    "component: select",
    "component: skeleton",
    "component: slider",
    "component: tabs",
    "component: textarea",
    "component: toggle",
    "component: toggle group",
    "component: tooltip",
    "component: typography",
    "chart: area",
    "chart: bar",
    "chart: line",
    "chart: pie",
    "chart: doughnut",
    "chart: radar",
    "chart: scatter",
]


def autocomplete_large_list():
    return autocomplete(
        items=ITEMS,
        placeholder="Search components and charts...",
    )

Custom Styling

Override any part of the component by passing a *_class prop. Classes are merged with the defaults via cn.

from components.ui.autocomplete import autocomplete


def autocomplete_custom_styling():
    return autocomplete(
        items=["feature", "fix", "bug", "docs", "internal", "mobile"],
        placeholder="Search tags...",
        input_class="h-10 rounded-full px-4 border-ring",
        popup_class="rounded-xl",
        item_class="rounded-full px-3",
        item_highlighted_class="bg-primary text-primary-foreground",
    )

Empty State

When no items match the query, the empty state is shown automatically.

from components.ui.autocomplete import autocomplete


def autocomplete_empty_state():
    return autocomplete(
        items=["feature", "fix", "bug"],
        placeholder="Try typing something that won't match...",
        empty_class="text-destructive py-6",
    )

API Reference

autocomplete

PropTypeDefaultDescription
itemslist[str][]The list of items to display in the dropdown.
placeholderstrNonePlaceholder text shown inside the input when empty.
on_change_queryEventHandlerNoneFired on every keystroke with the current input value.
on_select_itemEventHandlerNoneFired when an item is selected, with the selected value as argument.
root_classstrNoneAdditional Tailwind classes merged onto the root wrapper.
input_classstrNoneAdditional Tailwind classes merged onto the input element.
popup_classstrNoneAdditional Tailwind classes merged onto the dropdown popup.
list_classstrNoneAdditional Tailwind classes merged onto the scrollable list.
item_classstrNoneAdditional Tailwind classes merged onto each list item.
item_highlighted_classstrNoneAdditional Tailwind classes merged onto the currently highlighted item.
empty_classstrNoneAdditional Tailwind classes merged onto the empty state element.
set_query_on_selectboolTrueControls whether selecting an item updates the input value. If False, selection clears the input (useful for command palette / navigation mode).