[](#contributors-)
### Creating Groups
You can create groups with the `AutoCompleteGroup` Component, and add a title with the `AutoCompleteGroupTitle` component.
```js
import React from "react";
import {
AutoComplete,
AutoCompleteGroup,
AutoCompleteGroupTitle,
AutoCompleteInput,
AutoCompleteItem,
AutoCompleteList,
} from "@choc-ui/chakra-autocomplete";
import { Stack, Text } from "@chakra-ui/react";
export default function App() {
const continents = {
africa: ["nigeria", "south africa"],
asia: ["japan", "south korea"],
europe: ["united kingdom", "russia"],
};
return (
## Accessing the internal state
To access the internal state of the `AutoComplete`, use a function as children (commonly known as a render prop). You'll get access to the internal state `isOpen`, with the `onOpen` and `onClose` methods.
```js
import {
Flex,
Field,
Icon
} from "@chakra-ui/react";
import * as React from "react";
import {
AutoComplete,
AutoCompleteInput,
AutoCompleteItem,
AutoCompleteList,
} from "@choc-ui/chakra-autocomplete";
import { FiChevronRight, FiChevronDown } from "react-icons/fi";
import { InputGroup } from "./components/ui/input-group";
function App() {
const countries = [
"nigeria",
"japan",
"india",
"united states",
"south korea",
];
return (
## Custom Rendering
You can Render whatever you want. The `AutoComplete` Items are regular `Chakra` Boxes.
```js
import React from "react";
import {
AutoComplete,
AutoCompleteGroup,
AutoCompleteInput,
AutoCompleteItem,
AutoCompleteList,
} from "@choc-ui/chakra-autocomplete";
import { Stack, Text } from "@chakra-ui/react";
import { Avatar } from "./components/ui/avatar";
export default function App() {
const europeans = [
{ name: "Dan Abramov", image: "https://bit.ly/dan-abramov" },
{ name: "Kent Dodds", image: "https://bit.ly/kent-c-dodds" },
{ name: "Ryan Florence", image: "https://bit.ly/ryan-florence" },
];
const nigerians = [
{ name: "Segun Adebayo", image: "https://bit.ly/sage-adebayo" },
{ name: "Prosper Otemuyiwa", image: "https://bit.ly/prosper-baba" },
];
return (
## Multi Select with Tags
Add the `multiple` prop to `AutoComplete` component, the `AutoCompleteInput` will now expose the tags in it's children function.
The `onChange` prop now returns an array of the chosen `values`
Now you can map the tags with the `AutoCompleteTag` component or any other component of your choice. The `label` and the `onRemove` method are now exposed.
**Important** - With Chakra UI V3, it is no longer possible to replicate the same styling to the `Box` wrapper as what the underlying `Input` is using. We are still looking into ways to resolve this, but neither the Chakra nor next-themes teams have published guidance on this yet.
```js
import React from "react";
import {
AutoComplete,
AutoCompleteInput,
AutoCompleteItem,
AutoCompleteList,
AutoCompleteTag,
} from "@choc-ui/chakra-autocomplete";
import { Stack, Text } from "@chakra-ui/react";
export default function App() {
const countries = [
"nigeria",
"japan",
"india",
"united states",
"south korea",
];
return (
## Loading State
Need to pull data from API, but don't want your users to see a blank screen? You can enable the loading state by passing the `isLoading` prop to `AutoComplete`. By doing this, 2 other props will be enabled
1. `loadingIcon` on `AutoCompleteInput` will display some sort of loading icon on the right side of the input. By default, a `Spinner` will be displayed, but you can pass in any custom element to be rendered
2. `loadingState` on `AutoCompleteList` can display custom loading content when `isLoading` is `true`. All content will be rendered in the center of the list. By default, a `Spinner` will be displayed, but you can pass in any custom element to be rendered.
Best practice is to combine `setTimeout` and `useEffect` to create a debounce effect. This will prevent un-necessary API calls if your user types relatively quickly.
A working code demo can be found [here](https://codesandbox.io/s/choc-ui-chakra-autocomplete-loading-tfc8jz)
## Integration with Form Libraries
It is relatively easy to integrate with form libaries such as `React Hook Form`, `Formik`, and others. Working examples can be found in the `demos` folder of this repo. See the [Contributing](#contribute) section of this doc on how to clone and set it up for testing.
Does your favorite form library not have a working example? Submit a PR to get it added and help others using this library quickly get up and running.
## Autocomplete methods
Assign a ref to the `AutoComplete` component and call the available methods with:
```js
ref.current?.resetItems();
ref.current?.removeItem(itemValue);
```
### Codesandbox Link [Here](https://githubbox.com/anubra266/choc-autocomplete/tree/main/demo)
## API Reference
**NB**: Feel free to request any additional `Prop` in [Issues](https://github.com/anubra266/choc-autocomplete/issues/new/).
### **AutoComplete**
Wrapper and Provider for `AutoCompleteInput` and `AutoCompleteList`
**AutoComplete** composes [**Box**](https://chakra-ui.com/docs/components/box) so you can pass all Box props to change its style.
**NB:** None of the props passed to it are required.
| Prop | Type | Description | Default |
| closeOnBlur | boolean | close suggestions when input is blurred | true |
| closeOnSelect | boolean | close suggestions when a suggestions is selected | true when multiple=false, false when multiple=true |
| creatable | boolean | Allow addition of arbitrary values not present in suggestions | false |
| defaultIsOpen | boolean | Suggestions list is open by default | false |
| prefocusFirstItem | boolean | Should prefocus first item intially, on query change, on open, and on filter out of current focused item | true |
| defaultValues | Array | Used to predefine tags, or value for the autocomplete component. Just pass an array of the values | ——— |
| disableFilter | boolean | disables filtering when set to true | false |
| emphasize | boolean | SystemStyleObject | Highlight matching characters in suggestions, you can pass the styles - false | false |
| defaultEmptyStateProps | FlexProps | Props to pass into the `Flex` component when using the default empty state. Does not apply when you supply your own custom `emptyState` | ——— |
| emptyState | ```ts boolean | MaybeRenderProp<{ value: Item["value"] }> ``` | render message when no suggestions match query | true |
| filter | ```ts (query: string, optionValue: Item["value"], optionLabel: Item["label"]) => boolean; ``` | custom filter function | ——— |
| focusInputOnSelect | boolean | focus input after a suggestion is selected | true |
| freeSolo | boolean | allow entering of any arbitrary values | false |
| isReadOnly | boolean | Make the component read-only | false |
| isLoading | boolean | Display loading animation on both the input and list elements | false |
| isPortalled | boolean | Determines if the popover content should be rendered in a Portal. Set to false to render content in DOM hierarchy. Useful when rendering inside of a Dialog |
true |
| listAllValuesOnFocus | boolean | Show all suggestions when user focuses the input, while it's not empty. | false |
| matchWidth | boolean | Chakra UI Popover.positioning.sameWidth property to match the popover content's width to the width of the container | true |
| maxSelections | number | limit possible number of tag selections in multiple mode | ——— |
| maxSuggestions | number | limit number of suggestions in list | ——— |
| multiple | boolean | allow tags multi selection | false |
| onChange | ```ts (value: string | Item["value"][], item: Item| Item[]) => void ``` | function to run whenever autocomplete value(s) changes | ——— |
| onSelectOption | ```ts (params: { item: Item; selectMethod: "mouse" | "keyboard" | null; isNewInput: boolean; }) => boolean | void ``` | method to call whenever a suggestion is selected | ——— |
| onOptionFocus | ```ts (params: { item: Item; focusMethod: "mouse" | "keyboard" | null; isNewInput: boolean; }) => boolean | void ``` | method to call whenever a suggestion is focused | ——— |
| onReady | ```ts (props:{tags:ItemTag[]}) => void ``` | method that exposes variables used in component | ——— |
| onTagRemoved | ```ts (removedTag: Item["value"],item: Item, tags: Item["value"][]) => void ``` | method to call whenever a tag is removed | ——— |
| openOnFocus | boolean | open suggestions when input is focuses | false |
| placement | PlacementWithLogical | where autocomplete list will display. Accepts any valid value from Popover component | bottom |
| restoreOnBlurIfEmpty | boolean | if false, clearing the value of the input field will also clear the selected option | true |
| rollNavigation | boolean | allow keyboard navigation to switch to alternate ends when one end is reached | false |
| selectOnFocus | boolean | select the text in input when it's focused | false |
| shouldRenderSuggestions | ```ts (value: string) => boolean ``` | function to decide if suggestions should render, e.g. show suggestions only if there are at least two characters in the query value | ——— |
| submitKeys; | ```ts string[] ``` | A list of KeyboardEvent: key values, except for the "Enter" key, that trigger the click event of the currently selected Item. | ——— |
| suggestWhenEmpty | boolean | show suggestions when input value is empty | false |
| value | any | value of the component in the controlled state | --- |
| Prop |
Type | Description | Required | Default |
|---|---|---|---|---|
| disabled | string | In the event that you need to lock certain tag so that they can't be removed in the interface, you can set the tags disabled. | No |
——— |
| label | string | Label that is displayed on the tag | Yes |
——— |
| onRemove | ```ts () => void ``` | Method to remove the tag from selected values | Yes |
——— |
| Prop |
Type | Description | Required | Default |
|---|---|---|---|---|
| children | ```ts type children = MaybeRenderProp<{ tags: Item & { onRemove: () => void }[]; }>; ``` |
callback that returns `ReactNode` and is provided with tags in `multiple` mode
e.g.
```js
|
No |
——— |
| ref |
```js
RefObject |
provides a ref to the input element so the value can be referenced in additional contexts | No |
——— |
| hidePlaceholder | boolean | hides the placeholder when children is not an empty array. intended usage for
```js
|
No |
false |
| loadingIcon | React.ReactNode | JSX | Element that will be displayed when isLoading is true | No | Spinner from Chakra-UI |
| Prop |
Type | Description | Required | Default |
|---|---|---|---|---|
| loadingState | React.ReactNode | JSX | Content displayed in list while isLoading is true. Content will be centered | No | Spinner from Chakra-UI with an md size |
| Prop |
Type | Description | Required | Default |
|---|---|---|---|---|
| showDivider | boolean | If true, a divider is shown | No | false |
| dividerColor | string | Color for divider, if present | No | inherit |
| Prop |
Type | Description | Required | Default |
|---|---|---|---|---|
| getValue | (value:any) => any | A method used to determine the key that holds the value, when the value prop is an object | no |
```js val => val; ``` |
| label | string | The label for the Option | no |
——— |
| value | string or Object | The value of the Option | yes |
——— |
| fixed | boolean | Make an item visible at all times, regardless of filtering or maxSuggestions | No | ——— |
| _fixed | SystemStyleObject | Styles for fixed Itemm | No | ```js { fontWeight: 'extrabold', } ``` |
| value | string | The value of the Option | yes |
——— |
| disabled | boolean | Make an item disabled, so it cannot be selected | No | ——— |
| _disabled | SystemStyleObject | Styles for disabled Item(s) | No | ```js { fontWeight: 'extrabold', } ``` |
| _selected | SystemStyleObject | Styles for selected Item(s) | No | ```js { fontWeight: 'extrabold', } ``` |
| _focus | SystemStyleObject | Styles for focused Item | No | ```js { fontWeight: 'extrabold', } ``` |
| Prop |
Type | Description | Required | Default |
|---|---|---|---|---|
| children | ```ts type children = MaybeRenderProp<{ value: any }>; ``` |
`ReactNode` or callback that returns `ReactNode`
e.g.
```js
|
No |
——— |
| alwaysDisplay | ```ts boolean; ``` | When true, `AutoCompleteCreatable` is shown even when the `AutoCompleteInput` is empty | No |
——— |
