React API Search

A highly customizable, debounce-enabled, and fully-featured React API Search component designed to fetch and display search results asynchronously. Ideal for scenarios where the search query is used to fetch data from APIs or databases, with built-in support for loading, error handling, and no-result states.

Features

• Debounced Search: Customizable debounce delay to prevent excessive API calls while typing.
• Loading & Error States: Display loading spinners or error messages while fetching data.
• Dropdown Menu: A dropdown menu that displays search results, with full control over its visibility.
• Customizable Styles: Easily apply custom styles to the container, input field, results list, items, and icons.
• Flexible Data Fetching: Works with any asynchronous data-fetching method.
• TypeScript Support: Fully typed for better development experience and safety.

Installation

npm install react-api-search

or

yarn add react-api-search

Usage

import SearchBar from 'react-api-search';

type Post = {
  id: number;
  title: string;
  body: string;
};

const fetchPosts = async (query: string): Promise<Post[]> => {
  const response = await fetch(
    `https://jsonplaceholder.typicode.com/posts?q=${encodeURIComponent(query)}`
  );
  if (!response.ok) throw new Error('Failed to fetch posts');
  const data = await response.json();
  return data;
};

function App() {
  return (
    <div style={{ padding: '20px' }}>
      <h1>Posts Search</h1>
      <div style={{ width: '40rem' }}>
        <SearchBar<Post>
          placeholder='Search for posts...'
          fetchData={fetchPosts}
          loadingElement={
            <div className='custom-loading'>Please wait, fetching data...</div>
          }
          emptyElement={
            <div>No posts match your search. Try something else!</div>
          }
          errorElement={
            <div>Oops, something went wrong. Please try again later.</div>
          }
          renderItem={(post) => (
            <div
              style={{ padding: '10px', borderBottom: '1px solid #ccc' }}
              onMouseEnter={(e) => {
                e.currentTarget.style.backgroundColor = '#f0f0f0'; // hover background
              }}
              onMouseLeave={(e) => {
                e.currentTarget.style.backgroundColor = 'transparent'; // reset background
              }}
            >
              <h3 style={{ margin: 0 }}>{post.title}</h3>
              <p style={{ margin: '5px 0', fontSize: '0.9em', color: '#555' }}>
                {post.body}
              </p>
            </div>
          )}
          onSelect={(post) => alert(`Selected post: ${post.title}`)}
          debounceDelay={500}
        />
      </div>
    </div>
  );
}

export default App;

Props

Prop	Type	Description	Default Value
placeholder	string	Placeholder text for the input field.	'Search...'
fetchData	(query: string) => Promise<T[]>	A function that fetches data based on the search query.	N/A
renderItem	(item: T) => JSX.Element	A function to render each search result item.	N/A
onSelect	(item: T) => void	A callback function triggered when a user selects an item.	undefined
loadingElement	JSX.Element	JSX to display while results are loading.	<div>Loading...</div>
emptyElement	JSX.Element	JSX to display when no results are found.	<div>No results found</div>
errorElement	JSX.Element	JSX to display when an error occurs.	<div>Something went wrong</div>
debounceDelay	number	The debounce delay in milliseconds.	500
containerClassName	string	Custom class for the search bar container.	undefined
inputClassName	string	Custom class for the input field.	undefined
dropdownClassName	string	Custom class for the dropdown containing search results.	undefined
itemClassName	string	Custom class for each search result item.	undefined
hideSearchIcon	boolean	Whether to hide the search icon.	false
searchIconClassName	string	Custom class for the search icon.	undefined
closeIconClassName	string	Custom class for the close icon.	undefined
inputFontColor	string	Font color of the input field.	#000
inputBorderRadius	string	Border radius of the input field.	'8px'
inputBorderColor	string	Border color of the input field.	#ccc
inputFontSize	string	Font size of the input field.	'16px'
inputHeight	string	Height of the input field.	'45px'
inputBackgroundColor	string	Background color of the input field.	#fff
searchIconColor	string	Color of the search icon.	#888
closeIconColor	string	Color of the close icon.	#888
dropDownBackgroundColor	string	Background color of the dropdown.	#fff
dropDownBorderColor	string	Border color of the dropdown.	#ccc
dropDownMaxHeight	string	Maximum height of the dropdown.	'60vh'
dropDownBorderRadius	string	Border radius of the dropdown.	'8px'
scrollBarColor	string	Color of the scrollbar inside the dropdown.	#ccc

License

This project is licensed under the MIT License. See the LICENSE file for more information.

Contributing

Contributions are welcome! 🎉

1. Fork the project.
2. Create a feature branch (git checkout -b feature-name).
3. Commit your changes (git commit -m 'Add some feature').
4. Push to the branch (git push origin feature-name).
5. Open a Pull Request.

For more information, please checkout the CONTRIBUTIONS document.

---

Note: This component uses TypeScript and provides full type safety. It can be easily integrated into any TypeScript or JavaScript-based React project.