at-react-autocomplete-1


A highly customizable, keyboard-accessible autocomplete dropdown component for React + TypeScript.

✨ Features

• ⌨️ Full keyboard navigation (↑/↓ arrows, Enter, Escape)
• ⏳ Built-in debouncing for API calls
• 🔄 Loading state support
• 🎨 Customizable item rendering with renderItem
• 📏 Minimum search length requirement
• 🖱️ Mouse + keyboard interaction support
• 🛠 TypeScript-first design
• 🎛 Supports controlled or uncontrolled input
• 🎨 Accepts className for easy styling

📦 Installation

npm install at-react-autocomplete-1

# or
yarn add at-react-autocomplete-1

Basic Example

import React, { useState } from "react";
import AutocompleteDropdown from "at-react-autocomplete-1";

const fruits = ["Apple", "Banana", "Cherry", "Mango", "Orange"];

export default function Example() {
  const [options, setOptions] = useState<string[]>([]);
  const [loading, setLoading] = useState(false);

  const handleInputChange = (query: string) => {
    setLoading(true);
    setTimeout(() => {
      setOptions(
        fruits.filter((f) => f.toLowerCase().includes(query.toLowerCase()))
      );
      setLoading(false);
    }, 500);
  };

  return (
    <AutocompleteDropdown
      suggestions={options}
      onSelect={(item) => alert(`Selected: ${item}`)}
      onInputChange={handleInputChange} // 👈 mandatory
      isLoading={loading}
      placeholder="Search for a fruit..."
      className="my-4"
    />
  );
}

Props

Prop	Type	Required	Description
suggestions	T[]	✅	Array of suggestions to display
onInputChange	(value: string) => void	✅	Called when input changes (debounced)
onSelect	(item: T) => void	✅	Called when item is selected
renderItem	(item: T) => React.ReactNode	❌	Renders each dropdown item (default: text)
getDisplayValue	(item: T) => string	❌	Gets display value for input (default: item.toString())
inputValue	string	❌	Controlled input value
setInputValue	(value: string) => void	❌	Updates controlled input value
placeholder	string	❌	Input placeholder text
isLoading	boolean	❌	Shows loading indicator
minSearchLength	number	❌	Minimum chars before searching (default: 2)
debounceDelay	number	❌	Debounce delay in ms (default: 300)
className	string	❌	Custom class names for container

Advanced Example: Fetching from API

import React, { useState } from "react";
import AutocompleteDropdown from "at-react-autocomplete-1";

interface User {
  id: number;
  name: string;
  avatar: string;
}

export default function SearchUsers() {
  const [users, setUsers] = useState<User[]>([]);
  const [loading, setLoading] = useState(false);

  const fetchUsers = async (query: string) => {
    setLoading(true);
    const res = await fetch(`/api/users?q=${query}`);
    setUsers(await res.json());
    setLoading(false);
  };

  return (
    <AutocompleteDropdown<User>
      suggestions={users}
      onInputChange={fetchUsers}
      onSelect={(user) => console.log("Selected:", user)}
      renderItem={(user) => (
        <div className="flex items-center gap-2">
          <img
            src={user.avatar}
            alt={user.name}
            className="w-6 h-6 rounded-full"
          />
          <span>{user.name}</span>
        </div>
      )}
      getDisplayValue={(user) => user.name}
      isLoading={loading}
      minSearchLength={3}
    />
  );
}

Usage

<AutocompleteDropdown
  suggestions={options}
  onInputChange={handleInputChange}
  onSelect={(item) => console.log(item)}
  className="my-autocomplete"
/>

Usage with TypeScript example

interface City {
  id: string;
  name: string;
  country: string;
}

<AutocompleteDropdown<City>
  suggestions={cities}
  onSelect={(city) => console.log(city)}
  onInputChange={(q) => fetchCities(q)}
  renderItem={(city) => (
    <div>
      <strong>{city.name}</strong>, {city.country}
    </div>
  )}
  getDisplayValue={(city) => `${city.name}, ${city.country}`}
/>;

Do you also want me to add badges for CI status, bundle size (bundlephobia), and TypeScript support so it looks like a polished open-source package?