"use strict"; const {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0]; const {useMDXComponents: _provideComponents} = arguments[0]; function _createMdxContent(props) { const _components = { a: "a", code: "code", em: "em", h2: "h2", li: "li", ol: "ol", p: "p", pre: "pre", strong: "strong", table: "table", tbody: "tbody", td: "td", th: "th", thead: "thead", tr: "tr", ul: "ul", ..._provideComponents(), ...props.components }; return _jsxs(_Fragment, { children: [_jsx(_components.p, { children: "Every search input looks simple — until you ship it. Then you discover the API fires 30 requests per second, keyboard users can't navigate results, and screen readers announce nothing useful." }), "\n", _jsxs(_components.p, { children: ["Building a ", _jsx(_components.em, { children: "good" }), " autocomplete means solving four problems at once:"] }), "\n", _jsxs(_components.ol, { children: ["\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Performance:" }), " Avoiding API spam with every keystroke (debouncing)"] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Usability:" }), " Full keyboard navigation (Arrow keys, Enter, Escape)"] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Robustness:" }), " Loading states, empty results, outside click dismissal"] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Accessibility:" }), " Proper ARIA roles so screen readers work correctly"] }), "\n"] }), "\n", _jsxs(_components.p, { children: ["Here's how to build one from scratch with ", _jsx(_components.strong, { children: "React, TypeScript, and Tailwind CSS" }), " — and when you should reach for a library instead."] }), "\n", _jsx(_components.h2, { id: "the-tech-stack", children: "The Tech Stack" }), "\n", _jsxs(_components.ul, { children: ["\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "React 18+" }), " — functional components and hooks (", _jsx(_components.code, { children: "useState" }), ", ", _jsx(_components.code, { children: "useEffect" }), ", ", _jsx(_components.code, { children: "useRef" }), ")"] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "TypeScript" }), " — type safety and better developer experience"] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Tailwind CSS" }), " — rapid, utility-first styling"] }), "\n"] }), "\n", _jsxs(_components.h2, { id: "step-1-custom-usedebounce-hook", children: ["Step 1: Custom ", _jsx(_components.code, { children: "useDebounce" }), " Hook"] }), "\n", _jsxs(_components.p, { children: ["The biggest mistake with autocomplete is firing an API request on every ", _jsx(_components.code, { children: "onChange" }), " event. A fast typist generates dozens of requests per second. ", _jsx(_components.strong, { children: "Debouncing" }), " waits until the user stops typing before triggering the search."] }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-typescript", children: "// hooks/useDebounce.ts\nimport { useEffect, useState } from \"react\";\n\nexport function useDebounce(value: T, delay: number = 500): T {\n const [debouncedValue, setDebouncedValue] = useState(value);\n\n useEffect(() => {\n const timer = setTimeout(() => {\n setDebouncedValue(value);\n }, delay);\n\n // Cancel the timer if value changes before delay expires\n return () => {\n clearTimeout(timer);\n };\n }, [value, delay]);\n\n return debouncedValue;\n}\n" }) }), "\n", _jsxs(_components.p, { children: ["The cleanup function is the key — every new keystroke clears the previous timer, so the callback only fires after ", _jsx(_components.code, { children: "delay" }), " milliseconds of silence."] }), "\n", _jsx(_components.h2, { id: "step-2-component-structure-and-state", children: "Step 2: Component Structure and State" }), "\n", _jsx(_components.p, { children: "The component needs five pieces of state:" }), "\n", _jsxs(_components.ol, { children: ["\n", _jsxs(_components.li, { children: [_jsx(_components.code, { children: "query" }), " — what the user typed"] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.code, { children: "suggestions" }), " — results from the API"] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.code, { children: "isLoading" }), " — loading indicator"] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.code, { children: "isOpen" }), " — dropdown visibility"] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.code, { children: "activeIndex" }), " — keyboard-highlighted item (-1 = none)"] }), "\n"] }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-tsx", children: "// components/Autocomplete.tsx\nimport { useState, useEffect, useRef, KeyboardEvent } from \"react\";\nimport { useDebounce } from \"../hooks/useDebounce\";\n\nconst MOCK_DATA = [\n \"React\", \"Next.js\", \"Vue\", \"Svelte\", \"Angular\",\n \"TypeScript\", \"JavaScript\", \"Tailwind CSS\", \"Node.js\"\n];\n\n// Simulates a network request with 300ms latency\nconst mockApiSearch = async (query: string): Promise => {\n return new Promise((resolve) => {\n setTimeout(() => {\n const filtered = MOCK_DATA.filter((item) =>\n item.toLowerCase().includes(query.toLowerCase())\n );\n resolve(filtered);\n }, 300);\n });\n};\n\nexport function Autocomplete() {\n const [query, setQuery] = useState(\"\");\n const [suggestions, setSuggestions] = useState([]);\n const [isLoading, setIsLoading] = useState(false);\n const [isOpen, setIsOpen] = useState(false);\n const [activeIndex, setActiveIndex] = useState(-1);\n\n const dropdownRef = useRef(null);\n const debouncedQuery = useDebounce(query, 500);\n\n // ... effects, handlers, and JSX below\n}\n" }) }), "\n", _jsx(_components.h2, { id: "step-3-fetching-data-with-race-condition-protection", children: "Step 3: Fetching Data with Race Condition Protection" }), "\n", _jsxs(_components.p, { children: ["The fetch effect triggers whenever ", _jsx(_components.code, { children: "debouncedQuery" }), " changes. One subtle bug to watch for: if the user types \"re\", pauses, then types \"rea\" quickly, the response for \"re\" might arrive ", _jsx(_components.em, { children: "after" }), " the response for \"rea\" — showing stale results."] }), "\n", _jsxs(_components.p, { children: ["The ", _jsx(_components.code, { children: "cancelled" }), " flag prevents this by marking stale closures before applying their results."] }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-tsx", children: "// components/Autocomplete.tsx (continued)\n\n useEffect(() => {\n if (!debouncedQuery) {\n setSuggestions([]);\n setIsOpen(false);\n return;\n }\n\n let cancelled = false;\n\n const fetchData = async () => {\n setIsLoading(true);\n try {\n const results = await mockApiSearch(debouncedQuery);\n if (!cancelled) {\n setSuggestions(results);\n setIsOpen(true);\n setActiveIndex(-1);\n }\n } catch {\n if (!cancelled) {\n setSuggestions([]);\n }\n } finally {\n if (!cancelled) {\n setIsLoading(false);\n }\n }\n };\n\n fetchData();\n\n // If debouncedQuery changes before fetch resolves,\n // mark this closure as stale\n return () => {\n cancelled = true;\n };\n }, [debouncedQuery]);\n" }) }), "\n", _jsxs(_components.p, { children: ["For real APIs, you could replace the ", _jsx(_components.code, { children: "cancelled" }), " flag with an ", _jsx(_components.code, { children: "AbortController" }), " to also cancel the network request itself."] }), "\n", _jsx(_components.h2, { id: "step-4-keyboard-navigation", children: "Step 4: Keyboard Navigation" }), "\n", _jsx(_components.p, { children: "A good autocomplete keeps users on the keyboard. Arrow keys cycle through results, Enter selects, Escape closes." }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-tsx", children: "// components/Autocomplete.tsx (continued)\n\n const handleKeyDown = (e: KeyboardEvent) => {\n if (!isOpen || suggestions.length === 0) return;\n\n if (e.key === \"ArrowDown\") {\n e.preventDefault();\n setActiveIndex((prev) => (prev < suggestions.length - 1 ? prev + 1 : 0));\n } else if (e.key === \"ArrowUp\") {\n e.preventDefault();\n setActiveIndex((prev) => (prev > 0 ? prev - 1 : suggestions.length - 1));\n } else if (e.key === \"Enter\" && activeIndex >= 0) {\n handleSelect(suggestions[activeIndex]);\n } else if (e.key === \"Escape\") {\n setIsOpen(false);\n }\n };\n\n const handleSelect = (value: string) => {\n setQuery(value);\n setIsOpen(false);\n setActiveIndex(-1);\n // In a real app, call an onSelect callback prop here\n };\n" }) }), "\n", _jsxs(_components.p, { children: ["The ", _jsx(_components.code, { children: "e.preventDefault()" }), " on arrow keys stops the cursor from jumping to the start/end of the input while navigating."] }), "\n", _jsx(_components.h2, { id: "step-5-rendering-with-aria-attributes", children: "Step 5: Rendering with ARIA Attributes" }), "\n", _jsxs(_components.p, { children: ["The JSX combines the input, a conditional dropdown, and proper ARIA roles for screen reader support. The ", _jsx(_components.code, { children: "role=\"combobox\"" }), " and ", _jsx(_components.code, { children: "aria-activedescendant" }), " attributes let assistive technology announce the highlighted option."] }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-tsx", children: "// components/Autocomplete.tsx (render)\n\n return (\n

\n Search\n

\n setQuery(e.target.value)}\n onKeyDown={handleKeyDown}\n onFocus={() => query && setIsOpen(true)}\n placeholder=\"Search technologies...\"\n className=\"w-full px-4 py-2 border border-gray-300 rounded-lg focus:ring-2 focus:ring-blue-500 focus:border-transparent outline-none transition\"\n autoComplete=\"off\"\n role=\"combobox\"\n aria-autocomplete=\"list\"\n aria-expanded={isOpen}\n aria-controls=\"autocomplete-list\"\n aria-activedescendant={activeIndex >= 0 ? `item-${activeIndex}` : undefined}\n />\n {isLoading && (\n

\n \n

\n )}\n

\n\n {isOpen && suggestions.length > 0 && (\n \n {suggestions.map((item, index) => (\n handleSelect(item)}\n className={`px-4 py-2 cursor-pointer transition ${\n index === activeIndex\n ? \"bg-blue-100 text-blue-800\"\n : \"text-gray-700 hover:bg-gray-50\"\n }`}\n onMouseEnter={() => setActiveIndex(index)}\n >\n {item}\n \n ))}\n \n )}\n\n {isOpen && !isLoading && query && suggestions.length === 0 && (\n

\n No results found for “{query}”\n

\n )}\n

\n );\n" }) }), "\n", _jsx(_components.h2, { id: "step-6-handling-outside-clicks", children: "Step 6: Handling Outside Clicks" }), "\n", _jsxs(_components.p, { children: ["A polished component closes when clicking elsewhere. Attach a global ", _jsx(_components.code, { children: "mousedown" }), " listener and check if the click target falls outside the component's ref."] }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-typescript", children: "// components/Autocomplete.tsx (add this useEffect)\n\n useEffect(() => {\n const handleClickOutside = (event: MouseEvent) => {\n if (\n dropdownRef.current &&\n !dropdownRef.current.contains(event.target as Node)\n ) {\n setIsOpen(false);\n }\n };\n\n document.addEventListener(\"mousedown\", handleClickOutside);\n return () => {\n document.removeEventListener(\"mousedown\", handleClickOutside);\n };\n }, []);\n" }) }), "\n", _jsx(_components.h2, { id: "when-to-build-vs-use-a-library", children: "When to Build vs. Use a Library" }), "\n", _jsx(_components.p, { children: "This custom implementation works well for simple string-based searches. But if your requirements grow — multi-select, async loading indicators, grouped options, virtualized lists — consider a battle-tested library:" }), "\n", _jsxs(_components.table, { children: [_jsx(_components.thead, { children: _jsxs(_components.tr, { children: [_jsx(_components.th, { children: "Library" }), _jsx(_components.th, { children: "Best For" })] }) }), _jsxs(_components.tbody, { children: [_jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.a, { href: "https://github.com/downshift-js/downshift", rel: "nofollow", target: "_blank", children: "Downshift" }) }), _jsx(_components.td, { children: "Maximum flexibility, headless approach" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.a, { href: "https://www.radix-ui.com/", rel: "nofollow", target: "_blank", children: "Radix UI Combobox" }) }), _jsx(_components.td, { children: "Accessible primitives with styling freedom" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.a, { href: "https://headlessui.com/", rel: "nofollow", target: "_blank", children: "Headless UI Combobox" }) }), _jsx(_components.td, { children: "Tailwind-native, great with Tailwind CSS" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.a, { href: "https://react-select.com/", rel: "nofollow", target: "_blank", children: "React Select" }) }), _jsx(_components.td, { children: "Feature-rich, works out of the box" })] })] })] }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Build your own" }), " when you need a lightweight solution, want to understand the internals, or have constraints that don't fit existing libraries. ", _jsx(_components.strong, { children: "Use a library" }), " when you need complex features like virtualization, multi-select, or async option loading — the edge cases are harder than they look."] }), "\n", _jsx(_components.h2, { id: "conclusion", children: "Conclusion" }), "\n", _jsxs(_components.p, { children: ["This autocomplete handles the four core challenges: ", _jsx(_components.strong, { children: "debouncing" }), " prevents API spam, ", _jsx(_components.strong, { children: "keyboard navigation" }), " keeps power users happy, ", _jsx(_components.strong, { children: "race condition protection" }), " prevents stale results, and ", _jsx(_components.strong, { children: "ARIA attributes" }), " make it accessible."] }), "\n", _jsx(_components.p, { children: "From here, you can extend it to handle complex objects instead of strings, connect to a real backend API, or integrate with form libraries like React Hook Form. The patterns — debouncing, cleanup flags, keyboard handlers — transfer directly to production code." })] }); } function MDXContent(props = {}) { const {wrapper: MDXLayout} = { ..._provideComponents(), ...props.components }; return MDXLayout ? _jsx(MDXLayout, { ...props, children: _jsx(_createMdxContent, { ...props }) }) : _createMdxContent(props); } return { default: MDXContent };

Share this article

Table of Contents9 items