@choc-ui/chakra-autocomplete

🏇
@choc-ui/chakra-autocomplete

AutoComplete Component for the Chakra UI Library.

npm i @choc-ui/chakra-autocomplete

Install

npm i --save @choc-ui/chakra-autocomplete
#or
yarn add @choc-ui/chakra-autocomplete

Preview

With Mouse

With Keyboard

Demo on Codesandbox

Usage

Basic Usage

import {
  AutoComplete,
  AutoCompleteInput,
  AutoCompleteItem,
  AutoCompleteList,
} from '@choc-ui/chakra-autocomplete';

export default () => {
  const options = ['apple', 'appoint', 'zap', 'cap', 'japan'];

  return (
    <AutoComplete rollNavigation>
      <AutoCompleteInput
        variant="filled"
        placeholder="Search..."
        defaultValue="ap"
        autoFocus
      />
      <AutoCompleteList>
        {options.map((option, oid) => (
          <AutoCompleteItem
            key={`option-${oid}`}
            value={option}
            textTransform="capitalize"
          >
            {option}
          </AutoCompleteItem>
        ))}
      </AutoCompleteList>
    </AutoComplete>
  );
};

---

Creating Groups

You can create groups with the AutoCompleteGroup Component

import {
  AutoComplete,
  AutoCompleteGroup,
  AutoCompleteInput,
  AutoCompleteItem,
  AutoCompleteList,
} from '@choc-ui/chakra-autocomplete';

export default () => {
  const fruits = ['Apple', 'Grape', 'Pawpaw'];
  const countries = ['Korea', 'Nigeria', 'India'];

  return (
    <AutoComplete rollNavigation>
      <AutoCompleteInput
        variant="filled"
        placeholder="Search..."
        pl="10"
        defaultValue="ap"
        autoFocus
      />
      <AutoCompleteList>
        <AutoCompleteGroup title="Fruits" showDivider>
          {fruits.map((option, oid) => (
            <AutoCompleteItem
              key={`fruits-${oid}`}
              value={option}
              textTransform="capitalize"
            >
              {option}
            </AutoCompleteItem>
          ))}
        </AutoCompleteGroup>
        <AutoCompleteGroup title="countries" showDivider>
          {countries.map((option, oid) => (
            <AutoCompleteItem
              key={`countries-${oid}`}
              value={option}
              textTransform="capitalize"
            >
              {option}
            </AutoCompleteItem>
          ))}
        </AutoCompleteGroup>
      </AutoCompleteList>
    </AutoComplete>
  );
};

---

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 and method onClose.

import {
  AutoComplete,
  AutoCompleteInput,
  AutoCompleteItem,
  AutoCompleteList,
} from '@choc-ui/chakra-autocomplete';
import { ChevronDownIcon, ChevronRightIcon } from '@chakra-ui/icons';
import { Icon, InputGroup, InputRightElement } from '@chakra-ui/react';

export default () => {
  const options = ['apple', 'appoint', 'zap', 'cap', 'japan'];

  return (
    <AutoComplete rollNavigation>
      {({ isOpen }) => (
        <>
          <InputGroup>
            <AutoCompleteInput variant="filled" placeholder="Search..." />
            <InputRightElement
              children={
                <Icon as={isOpen ? ChevronRightIcon : ChevronDownIcon} />
              }
            />
          </InputGroup>
          <AutoCompleteList>
            {options.map((option, oid) => (
              <AutoCompleteItem
                key={`optio-${oid}`}
                value={option}
                textTransform="capitalize"
                align="center"
              >
                {option}
              </AutoCompleteItem>
            ))}
          </AutoCompleteList>
        </>
      )}
    </AutoComplete>
  );
};

Watch the Icon on the right.

---

Custom Rendering

You can Render whatever you want. The AutoComplete Items are regular Chakra Boxes.

import {
  AutoComplete,
  AutoCompleteInput,
  AutoCompleteItem,
  AutoCompleteList,
} from '@choc-ui/chakra-autocomplete';
import { Avatar, Box, Text } from '@chakra-ui/react';

export default () => {
  const people = [
    { name: 'Dan Abramov', image: 'https://bit.ly/dan-abramov' },
    { name: 'Kent Dodds', image: 'https://bit.ly/kent-c-dodds' },
    { name: 'Segun Adebayo', image: 'https://bit.ly/sage-adebayo' },
    { name: 'Prosper Otemuyiwa', image: 'https://bit.ly/prosper-baba' },
    { name: 'Ryan Florence', image: 'https://bit.ly/ryan-florence' },
  ];

  return (
    <AutoComplete rollNavigation>
      <AutoCompleteInput
        variant="filled"
        placeholder="Search..."
        pl="10"
        defaultValue="ap"
        autoFocus
      />
      <AutoCompleteList>
        {people.map((person, oid) => (
          <AutoCompleteItem
            key={`option-${oid}`}
            value={person.name}
            textTransform="capitalize"
            align="center"
          >
            <Avatar size="sm" name={person.name} src={person.image} />
            <Text ml="4">{person.name}</Text>
          </AutoCompleteItem>
        ))}
      </AutoCompleteList>
    </AutoComplete>
  );
};

---

API Reference

NB: Feel free to request any additional Prop in Issues.

AutoComplete

Wrapper and Provider for AutoCompleteInput and AutoCompleteList

AutoComplete composes Box so you can pass all Box props to change its style.

Prop	Type	Description	Required	Default
children	type children = |ReactNode | (props: { isOpen: boolean; onClose: () => void; inputIsEmpty: boolean; resetInput: () => void; }) => ReactNode;	Children can be a function which is provided with the isOpen, onClose, inputIsEmpty, and resetInput props.	No	———
onChange	type onChange = (value: string) => void;	Callback for when the autocomplete value changes, and when input changes if in freeSolo mode - returns the value.	No	———
emptyState	type emptyState = boolean | ReactNode;	Component to display when no options are found. set to true to use default.	No	No Options Found
rollNavigation	boolean	set to true to allow keyboard navigation to restart on both ends.	No	false
focusInputOnSelect	boolean	Determines if Input should be focused after an option is selected.	No	false
freeSolo	boolean	Set freeSolo to true so the textbox can contain any arbitrary value.	No	false
creatable	boolean	Allows creation of new Items, set to true to show `Add {newInput}` It can also be a function that returns a `ReactNode` and is provided with the `newInput` and an `Emphasize` component. e.g. const creatable={({ newInput, Emphasize }) => ( <> Add<Emphasize>"{newInput}"</Emphasize> </> )} When using creatable, freeSolo must be true.	No	false
selectOnFocus	boolean	select the text in input when input is focused	No	false
openOnFocus	boolean	Open the suggestions once input is focused.	No	false
emphasize	type emphasize = boolean | CSSObject;	The parts of the option string that match the `AutoCompleteInput` value are emphasized. Pass boolean to bolden it, or a Chakra `CSSObject` for custom styling.	No	false
defaultIsOpen	boolean	If true, the suggestions menu is open by default	No	false
onSelectOption	type onSelectOption= (params: { optionValue: string; selectMethod: 'click' | 'keyboard'; isNewInput: boolean; }) => boolean | void;	Will be called every time suggestion is selected via mouse or keyboard. It returns the selectedValue, the selectionMethod and a boolean specifying if the input is a new one; useFul when combined with creatable mode.	No	———
suggestWhenEmpty	boolean	Return false to prevent selecting the option.	No	false
closeOnBlur	boolean	If true, the menu will close when the AutoComplete Component loses focus.	No	true
closeOnselect	boolean	If true, the menu will close when an item is selected, by mouse or keyboard.	No	true
maxSuggestions	number	Limit the maximum number of suggestions that is shown.	No	———
shouldRenderSuggestions	(value: string) => boolean	By default, suggestions are rendered when the input isn't blank. Feel free to override this behaviour. This function gets the current value of the input e.g. The following function is to show the suggestions only if the input has more than two characters. function shouldRenderSuggestions(value) { return value.trim().length > 2; }	No	———

AutoCompleteInput

Input for AutoComplete value.

AutoCompleteInput composes Input so you can pass all Input props to change its style.

Prop	Type	Description	Required	Default
initialFilter	boolean	determines if the options are filtered by default, when a `defaultValue` is provided to the input.	No	true

AutoCompleteList

Wrapper for AutoCompleteGroup and AutoCompleteItem

AutoCompleteList composes Box so you can pass all Box props to change its style.

AutoCompleteGroup

Wrapper for collections of AutoCompleteItems

AutoCompleteGroup composes Box so you can pass all Box props to change its style.

Prop	Type	Description	Required	Default
title	string	The group title	No	———
titleStyles	TextProps	Styles for title decoration, if present	No	const baseTitleStyles: TextProps = { ml: '5', mt: '0.5rem', fontSize: 'xs', letterSpacing: 'wider', fontWeight: 'extrabold', textTransform: 'uppercase', };
showDivider	boolean	If true, a divider is shown	No	false
dividerColor	string	Color for divider, if present	No	inherit

AutoCompleteItem

This Composes your suggestions

AutoCompleteItem composes Flex so you can pass all Flex props to change its style.

Prop	Type	Description	Required	Default
value	string	The value of the Option	yes	———
_focus	CSSObject	Styles for focused Item	No	{ fontWeight: 'extrabold', }

AutoCompleteFixedItem

This is an item that is not filtered with the other options, but syncs with the highlight and active states.

AutoCompleteFixedItem composes Flex so you can pass all Flex props to change its style.

AutoCompleteFixedItem composes AutoCompleteItem so you can pass all AutoCompleteItem props to change its style.

Prop	Type	Description	Required	Default
onItemSelect	type onItemSelect = (method: 'click' | 'keyboard') => void;	Callback to run when Item is selected my mouse or keyboard. Provides the select method	No	———

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Abraham 💻

Sam Margalit 📖

gepd 💻

This project follows the all-contributors specification. Contributions of any kind welcome!