## Overview [#overview] The **Autocomplete** component provides an interactive text input with real-time suggestions. Built on Base UI primitives, it supports filtering, custom rendering, grouping, async data loading, and multiple size variants. ## Usage [#usage] ```tsx import { Autocomplete, AutocompleteContent, AutocompleteEmpty, AutocompleteInput, AutocompleteItem, AutocompleteList, } from "@tilt-legal/cubitt-components/primitives"; ``` ```tsx No tags found. {(tag) => ( {tag.value} )} ``` ## Examples [#examples] ### Auto Highlight [#auto-highlight] Automatically highlights the first matching item as you type. ```tsx import { Autocomplete, AutocompleteContent, AutocompleteEmpty, AutocompleteInput, AutocompleteItem, AutocompleteList, } from "@tilt-legal/cubitt-components/primitives"; import { Label } from "@tilt-legal/cubitt-components/primitives"; No tags found. {(tag) => ( {tag.value} )} ; ``` ### Clear Button [#clear-button] Add a clear button to quickly reset the input value. ```tsx import { AutocompleteClear, AutocompleteContent, AutocompleteEmpty, AutocompleteInput, AutocompleteItem, AutocompleteList, AutocompleteWrapper, } from "@tilt-legal/cubitt-components/primitives"; import { useState } from "react"; import { Autocomplete } from "@tilt-legal/cubitt-components/primitives"; import { Label } from "@tilt-legal/cubitt-components/primitives"; const [value, setValue] = useState(""); const filteredItems = tags.filter((item) => item.value.toLowerCase().includes(value.toLowerCase()) ); item.value} > No tags found. {(tag) => ( {tag.value} )} ; ``` ### Grouped Items [#grouped-items] Organize suggestions into categorized groups with labels. ```tsx import { Autocomplete, AutocompleteClear, AutocompleteCollection, AutocompleteContent, AutocompleteEmpty, AutocompleteGroup, AutocompleteGroupLabel, AutocompleteInput, AutocompleteItem, AutocompleteList, InputWrapper, } from "@tilt-legal/cubitt-components/primitives"; import { Avatar, AvatarFallback, AvatarImage } from "@tilt-legal/cubitt-components/primitives"; import { Label } from "@tilt-legal/cubitt-components/primitives"; const [value, setValue] = React.useState(""); const [open, setOpen] = React.useState(false); item.name} filter={null} > {open && ( {filteredItems.length === 0 ? ( No matching users found. ) : ( {(group) => ( {group.group} {(item) => ( {item.name .split(" ") .map((n) => n[0]) .join("")}
{item.name}
{item.position}
)} )} )} )} ; ``` ### Async Search [#async-search] Load suggestions dynamically from an API with loading states. ```tsx import { Autocomplete, AutocompleteClear, AutocompleteContent, AutocompleteInput, AutocompleteItem, AutocompleteList, AutocompleteStatus, InputWrapper, } from "@tilt-legal/cubitt-components/primitives"; import { Avatar, AvatarFallback, AvatarImage } from "@tilt-legal/cubitt-components/primitives"; import { Label } from "@tilt-legal/cubitt-components/primitives"; import { AutocompleteContent, AutocompleteEmpty, AutocompleteInput, AutocompleteItem, AutocompleteList, AutocompleteValue, Label, } from "@tilt-legal/cubitt-components/primitives"; import { Loader2 } from "@tilt-legal/cubitt-icons/ui/outline"; const [searchValue, setSearchValue] = React.useState(""); const [isLoading, setIsLoading] = React.useState(false); const [searchResults, setSearchResults] = React.useState([]); React.useEffect(() => { if (!searchValue) { setSearchResults([]); return; } setIsLoading(true); const timeoutId = setTimeout(async () => { const results = await fetchDevelopers(searchValue); setSearchResults(results); setIsLoading(false); }, 300); return () => clearTimeout(timeoutId); }, [searchValue]); item.name} filter={null} > {searchValue && ( {isLoading ? (
Searching...
) : ( `${searchResults.length} results found` )} {(developer) => ( {developer.name .split(" ") .map((n) => n[0]) .join("")}
{developer.name}
{developer.role} • {developer.location}
)} )} ; ``` ### Fuzzy Matching [#fuzzy-matching] Advanced fuzzy search with highlighted matches using `match-sorter`. ```tsx import * as React from "react"; import { Autocomplete } from "@tilt-legal/cubitt-components/primitives"; import { AutocompleteContent, AutocompleteEmpty, AutocompleteInput, AutocompleteItem, AutocompleteList, Label, useAutocompleteFilter, } from "@tilt-legal/cubitt-components/primitives"; import { matchSorter } from "match-sorter"; export default function FuzzyMatchingExample() { return ( item.title} > No results found for "" {(item) => ( {(value) => (
{highlightText(item.title, value)}
{highlightText(item.description, value)}
)} )} ); } function highlightText(text: string, query: string): React.ReactNode { const trimmed = query.trim(); if (!trimmed) return text; const escaped = trimmed.slice(0, 100).replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); const regex = new RegExp(`(${escaped})`, "gi"); return text.split(regex).map((part, idx) => regex.test(part) ? ( {part} ) : ( part ) ); } function fuzzyFilter(item: unknown, query: string): boolean { if (!query) return true; const fuzzyItem = item as FuzzyItem; const results = matchSorter([fuzzyItem], query, { keys: [ "title", "description", "category", { key: "title", threshold: matchSorter.rankings.CONTAINS }, { key: "description", threshold: matchSorter.rankings.WORD_STARTS_WITH }, ], }); return results.length > 0; } interface FuzzyItem { title: string; description: string; category: string; } const fuzzyItems: FuzzyItem[] = [ { title: "React Hooks Guide", description: "Learn how to use React Hooks like useState, useEffect, and custom hooks", category: "React", }, // ... more items ]; ``` ### Virtualized List [#virtualized-list] Handle large datasets efficiently with `@tanstack/react-virtual`. This example demonstrates virtualization with 10, 000 items. ```tsx import * as React from "react"; import { Autocomplete } from "@tilt-legal/cubitt-components/primitives"; import { AutocompleteClear, AutocompleteContent, AutocompleteEmpty, AutocompleteInput, AutocompleteItem, AutocompleteList, InputWrapper, } from "@tilt-legal/cubitt-components/primitives"; import { useVirtualizer } from "@tanstack/react-virtual"; export default function VirtualizedExample() { const [open, setOpen] = React.useState(false); const [searchValue, setSearchValue] = React.useState(""); const scrollElementRef = React.useRef(null); const { contains } = useAutocompleteFilter({ sensitivity: "base" }); const filteredItems = React.useMemo(() => { if (!searchValue) return virtualItems; return virtualItems.filter((item) => contains(item, searchValue)); }, [contains, searchValue]); const virtualizer = useVirtualizer({ enabled: open, count: filteredItems.length, getScrollElement: () => scrollElementRef.current, estimateSize: () => 32, overscan: 20, paddingStart: 8, paddingEnd: 8, }); const handleScrollElementRef = React.useCallback( (element: HTMLDivElement) => { scrollElementRef.current = element; if (element) virtualizer.measure(); }, [virtualizer] ); const totalSize = virtualizer.getTotalSize(); return ( No items found. {filteredItems.length > 0 && (
{virtualizer.getVirtualItems().map((virtualItem) => { const item = filteredItems[virtualItem.index]; if (!item) return null; return ( {item} ); })}
)} ); } const virtualItems = Array.from({ length: 10000 }, (_, i) => { const indexLabel = String(i + 1).padStart(4, "0"); return `Item ${indexLabel}`; }); ``` ### Size Variants [#size-variants] Three size variants: small, medium (default), and large. ```tsx import { Autocomplete } from "@tilt-legal/cubitt-components/primitives"; import { Label } from "@tilt-legal/cubitt-components/primitives"; // Small {value && } {(tag) => {tag.value}} // Medium (default) {value && } {(tag) => {tag.value}} // Large {value && } {(tag) => {tag.value}} ``` ## API Reference [#api-reference] ### Autocomplete [#autocomplete] | Prop | Type | Description | | ------------------- | ----------------------------------------------- | --------------------------------------------------------------------- | | `items` | `T[]` | Array of items to display in the autocomplete list. **Required** | | `value` | `string \| number \| string[]` | The controlled value of the input. | | `defaultValue` | `string \| number \| string[]` | The default value when uncontrolled. | | `onValueChange` | `(value: string \| number \| string[]) => void` | Callback fired when the input value changes. | | `open` | `boolean` | The controlled open state of the popup. | | `defaultOpen` | `boolean` | The default open state when uncontrolled. Defaults to `false`. | | `onOpenChange` | `(open: boolean, eventDetails) => void` | Callback fired when the open state changes. | | `autoHighlight` | `boolean` | Automatically highlight the first matching item. Defaults to `false`. | | `filter` | `(item: T, value: string) => boolean \| null` | Custom filter function. Set to `null` to disable filtering. | | `itemToStringValue` | `(item: T) => string` | Function to convert an item to a string value. | | `name` | `string` | Identifies the field when a form is submitted. | | `disabled` | `boolean` | Whether the autocomplete is disabled. Defaults to `false`. | | `readOnly` | `boolean` | Whether the autocomplete is read-only. Defaults to `false`. | | `className` | `string` | Additional CSS classes for the root element. | ### AutocompleteInput [#autocompleteinput] | Prop | Type | Description | | ----------- | ---------------------- | -------------------------------------- | | `size` | `"sm" \| "md" \| "lg"` | Size of the input. Defaults to `"md"`. | | `className` | `string` | Additional CSS classes for the input. | ### AutocompleteClear [#autocompleteclear] Button to clear the input value. | Prop | Type | Description | | ----------- | ----------- | -------------------------------------------- | | `children` | `ReactNode` | Custom icon/content for the clear button. | | `className` | `string` | Additional CSS classes for the clear button. | ### AutocompleteWrapper [#autocompletewrapper] Container for the input and clear button. Styled like `InputWrapper` and automatically serves as the anchor for popup positioning. | Prop | Type | Description | | ----------- | -------- | ----------------------------------------- | | `className` | `string` | Additional CSS classes for the container. | ### AutocompleteContent [#autocompletecontent] Wrapper for the popup content, portal, and positioner. | Prop | Type | Description | | -------------- | ------------------------------ | ----------------------------------------------------------- | | `align` | `"start" \| "center" \| "end"` | Alignment of the popup. Defaults to `"start"`. | | `side` | `"top" \| "bottom"` | Side of the input to display popup. Defaults to `"bottom"`. | | `sideOffset` | `number` | Offset from the input in pixels. Defaults to `4`. | | `alignOffset` | `number` | Offset along the alignment axis. Defaults to `0`. | | `showBackdrop` | `boolean` | Whether to show a backdrop overlay. Defaults to `false`. | | `className` | `string` | Additional CSS classes for the popup. | ### AutocompleteList [#autocompletelist] Container for autocomplete items. | Prop | Type | Description | | ----------- | --------------------------- | ------------------------------------ | | `children` | `(item: T) => ReactElement` | Render function for each item. | | `className` | `string` | Additional CSS classes for the list. | ### AutocompleteItem [#autocompleteitem] Individual selectable option. | Prop | Type | Description | | ----------- | -------- | ------------------------------------ | | `value` | `T` | The item value. | | `className` | `string` | Additional CSS classes for the item. | ### AutocompleteGroup [#autocompletegroup] Groups related items together. | Prop | Type | Description | | ----------- | -------- | ------------------------------------- | | `items` | `T[]` | Array of items in this group. | | `className` | `string` | Additional CSS classes for the group. | ### AutocompleteGroupLabel [#autocompletegrouplabel] Label for a group of items. | Prop | Type | Description | | ----------- | -------- | ------------------------------------------- | | `className` | `string` | Additional CSS classes for the group label. | ### AutocompleteCollection [#autocompletecollection] Nested collection for rendering grouped items. | Prop | Type | Description | | ---------- | --------------------------- | ------------------------------ | | `children` | `(item: T) => ReactElement` | Render function for each item. | ### AutocompleteEmpty [#autocompleteempty] Message displayed when no items match the search. | Prop | Type | Description | | ----------- | -------- | ------------------------------------------- | | `className` | `string` | Additional CSS classes for the empty state. | ### AutocompleteStatus [#autocompletestatus] Status message displayed above the list (e.g., loading, results count). | Prop | Type | Description | | ----------- | -------- | -------------------------------------- | | `className` | `string` | Additional CSS classes for the status. |