Last modified: 4/Oct/2024

AutoComplete

Enables users to quickly find and select from a pre-populated list of values as they type.

#Usage

import { AutoComplete } from '@kinsta/stratus'

const myRecords = ['record', 'other-record']
const handleSelect = () => {
  //...
}

const MyComponent = () => (
  <AutoComplete searchIndex={myRecords} onSelect={handleSelect} />
)

To create groups in AutoComplete, you can use getGroupIdentifier. This method must return a unique string id to the groups.

import { AutoComplete } from '@kinsta/stratus'

const myRecords = [{
  group: 'fruit',
  name: 'Apple',
}, {
  group: 'fruit',
  name: 'Chestnut',
}, {
  group: 'vegetable',
  name: 'Cucumber',
}]

const MyComponent = () => (
  <AutoComplete
    searchIndex={myRecords}
    getSearchAttribute={({ group, name }) => `${group} - ${name}`}
    getGroupIdentifier={({ group }) => group}
    getDisplayName={({ name }) => name}
  />
)

#Props

#children

ReactElement<HTMLInputElement, string | JSXElementConstructor<any>> & ReactNode

Alternative input element to search

#onSearch

(query: string) => void

Callback on changing the input's value

#onSelect

(item: T) => void

Callback on selecting an option

#floatingTag

keyof IntrinsicElements | ComponentType

Custom element for the floating wrapper

#itemTag

keyof IntrinsicElements | ComponentType<AutoCompleteResultItemProps>

Custom element for a single item (only used when no renderItem prop provided)

#placeholder

string

Placeholder for the input element

#label

string | ReactElement<any, string | JSXElementConstructor<any>>

Content of the label

#description

string | ReactElement<any, string | JSXElementConstructor<any>>

Content of the description

#errorMessage

string | ReactElement<any, string | JSXElementConstructor<any>>

It displays the given string as the content of the error message.

#hasError

boolean

Set the error state of the select

#renderItem

(searchRecord: T, isActive: boolean) => ReactElement<any, string | JSXElementConstructor<any>>

Customizes the items on the search

#noResultsComponent

ReactNode

Customizes the 'No results' screen

#value

string

The value of the custom input element

#onChange

(value: string) => unknown

Controls the change events

#getSearchAttribute

(record: T) => string

It returns the searched text

#getGroupIdentifier

(record: T) => string

Allows grouping in AutoComplete items by deduce an identifier based on the element

#getDisplayName

(record: T) => string

Customize the display of the selected text on the button. Its useful when you have a complex searchAttribute.

#getValue

(record: T) => string

Gets the value from the item. It's useful when the searchAttribute and the value consumed by the form are different.

#renderGroupLabel

(record: T) => string | ReactElement<any, string | JSXElementConstructor<any>>

Customizes a groups label by deducing it from an item. This prop has no effect without providing getGroupIdentifier.

#shouldSetInputValueOnSelect

boolean

It sets the the value upon selecting it from the list

#shouldSetInputValueOnBrowse

boolean

It instantly sets the value upon searching

#shouldOpenOnFocus

boolean

Dropdown opens upon input gaining focus

#shouldClearOnBlur

boolean

Whether should remove the current input value and reset to previous if there is no item selected

#onBrowse

(record: T, index: number) => void

A function that is called during the process of search

#customSearchMethod

SearchMethod<T>

A custom function that replaces the default search method

#isOpen

boolean

Controls the dropdown whether it's open or closed

#onClear

() => void

Callback on clearing the input (this prop only works when the children prop is not used)

#allowFreeText

boolean

Allow free text for the autocomplete input

#placement

Placement

Decides the placement of the dropdown

#isWidthAdjusted

boolean

Adjust the width of the items to the parent width

#isPortalDisabled

boolean

By default the floating element is rendered into a React portal to avoid stacking context issues. You can disable this behaviour and render the element next to the reference

#isDisabled

boolean

Sets the disabled state of the select input and prevents opening it

#prefixItem

ReactNode

Content of the prefix of the input

#results

Required

T[]

#searchIndex

Required

T[]

#Types

AutoCompleteInterface<T>: props of the AutoComplete component processed by stratus extended by Omit<HTMLAttributes<HTMLInputElement>, 'results' | 'onChange' | 'onSelect'>. Note that this is a generic type where you can specify the type of the records.
AutoCompleteResultItemProps: props of the AutoComplete.ResultItem