|
1 | | -# React SearchBar Component |
2 | | - |
3 | | -A highly customizable, debounce-enabled, and fully-featured React SearchBar 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. |
4 | | - |
5 | | -## Features |
6 | | - |
7 | | -- **Debounced Search**: Customizable debounce delay to prevent excessive API calls while typing. |
8 | | -- **Loading & Error States**: Display loading spinners or error messages while fetching data. |
9 | | -- **Dropdown Menu**: A dropdown menu that displays search results, with full control over its visibility. |
10 | | -- **Customizable Styles**: Easily apply custom styles to the container, input field, results list, items, and icons. |
11 | | -- **Flexible Data Fetching**: Works with any asynchronous data-fetching method. |
12 | | -- **TypeScript Support**: Fully typed for better development experience and safety. |
13 | | - |
14 | | -## Installation |
15 | | - |
16 | | -```bash |
17 | | -npm install type-search-api |
18 | | -``` |
19 | | - |
20 | | -or |
21 | | - |
22 | | -```bash |
23 | | -yarn add type-search-api |
24 | | -``` |
25 | | - |
26 | | -## Usage |
27 | | - |
28 | | -```tsx |
29 | | -import React, { useState } from 'react'; |
30 | | -import SearchBar from 'react-searchbar-component'; |
31 | | - |
32 | | -const MyComponent = () => { |
33 | | - const [selectedItem, setSelectedItem] = useState(null); |
34 | | - |
35 | | - const fetchSearchResults = async (query: string) => { |
36 | | - const response = await fetch(\`https://api.example.com/search?q=\${query}\`); |
37 | | - const data = await response.json(); |
38 | | - return data.results; // return an array of results |
39 | | - }; |
40 | | -
|
41 | | - const renderSearchResult = (item: any) => <div>{item.name}</div>; |
42 | | -
|
43 | | - const handleItemSelect = (item: any) => { |
44 | | - setSelectedItem(item); |
45 | | - }; |
46 | | -
|
47 | | - return ( |
48 | | - <div> |
49 | | - <SearchBar |
50 | | - fetchData={fetchSearchResults} |
51 | | - renderItem={renderSearchResult} |
52 | | - onSelect={handleItemSelect} |
53 | | - placeholder="Search for items..." |
54 | | - debounceDelay={300} |
55 | | - /> |
56 | | - {selectedItem && <div>You selected: {selectedItem.name}</div>} |
57 | | - </div> |
58 | | - ); |
59 | | -}; |
60 | | -
|
61 | | -export default MyComponent; |
62 | | -``` |
63 | | - |
64 | | -## Props |
65 | | - |
66 | | -| Prop | Type | Description | Default Value | |
67 | | -| --------------------- | --------------------------------- | ---------------------------------------------------------- | --------------------------------- | |
68 | | -| `placeholder` | `string` | Placeholder text for the input field. | `'Search...'` | |
69 | | -| `fetchData` | `(query: string) => Promise<T[]>` | A function that fetches data based on the search query. | N/A | |
70 | | -| `renderItem` | `(item: T) => JSX.Element` | A function to render each search result item. | N/A | |
71 | | -| `onSelect` | `(item: T) => void` | A callback function triggered when a user selects an item. | `undefined` | |
72 | | -| `loadingElement` | `JSX.Element` | JSX to display while results are loading. | `<div>Loading...</div>` | |
73 | | -| `emptyElement` | `JSX.Element` | JSX to display when no results are found. | `<div>No results found</div>` | |
74 | | -| `errorElement` | `JSX.Element` | JSX to display when an error occurs. | `<div>Something went wrong</div>` | |
75 | | -| `debounceDelay` | `number` | The debounce delay in milliseconds. | `500` | |
76 | | -| `containerClassName` | `string` | Custom class for the search bar container. | `undefined` | |
77 | | -| `inputClassName` | `string` | Custom class for the input field. | `undefined` | |
78 | | -| `dropdownClassName` | `string` | Custom class for the dropdown containing search results. | `undefined` | |
79 | | -| `itemClassName` | `string` | Custom class for each search result item. | `undefined` | |
80 | | -| `hideSearchIcon` | `boolean` | Whether to hide the search icon. | `false` | |
81 | | -| `searchIconClassName` | `string` | Custom class for the search icon. | `undefined` | |
82 | | -| `closeIconClassName` | `string` | Custom class for the close icon. | `undefined` | |
83 | | -
|
84 | | -## Example |
85 | | -
|
86 | | -### Basic Example |
87 | | -
|
88 | | -```tsx |
89 | | -<SearchBar |
90 | | - fetchData={async (query: string) => { |
91 | | - const response = await fetch(\`https://api.example.com/search?q=\${query}\`); |
92 | | - return response.json(); |
93 | | - }} |
94 | | - renderItem={(item) => <div>{item.name}</div>} |
95 | | - onSelect={(item) => console.log('Selected:', item)} |
96 | | - placeholder="Search for items..." |
97 | | - loadingElement={<div>Loading...</div>} |
98 | | - emptyElement={<div>No results found</div>} |
99 | | -/> |
100 | | -``` |
101 | | - |
102 | | -### Customizing the Appearance |
103 | | - |
104 | | -You can customize the appearance of the search bar using the following props: |
105 | | - |
106 | | -- `containerClassName` |
107 | | -- `inputClassName` |
108 | | -- `dropdownClassName` |
109 | | -- `itemClassName` |
110 | | -- `searchIconClassName` |
111 | | -- `closeIconClassName` |
112 | | - |
113 | | -These props allow you to apply your custom styles or use CSS modules. |
114 | | - |
115 | | -## License |
116 | | - |
117 | | -MIT License. © Karl 2024 |
118 | | - |
119 | | -## Contributing |
120 | | - |
121 | | -We welcome contributions to the project. Please fork the repository, create a new branch, make your changes, and open a pull request. |
122 | | - |
123 | | ---- |
124 | | - |
125 | | -**Note**: This component uses TypeScript and provides full type safety. It can be easily integrated into any TypeScript or JavaScript-based React project. |
0 commit comments