Autocomplete

This component allows the user to select from suggested options

Basic Usage


import { Autocomplete } from '@krakentech/coral';
 
<Autocomplete
    label="Energy providers"
    options={[
        { value: 'lobster', label: 'Lobster' },
        { value: 'prawn', label: 'Prawn' },
        { value: 'crab', label: 'Crab' },
        { value: 'octopus', label: 'Octopus' },
    ]}
/>;

Energy providers

Properties

defaultValue


<Autocomplete
    label="Energy providers"
    options={[
        { value: 'lobster', label: 'Lobster' },
        { value: 'prawn', label: 'Prawn' },
        { value: 'crab', label: 'Crab' },
        { value: 'octopus', label: 'Octopus' },
    ]}
    defaultValue="Lobster"
/>

Energy providers

disabled


<Autocomplete
    label="Energy providers"
    options={[
        { value: 'lobster', label: 'Lobster' },
        { value: 'prawn', label: 'Prawn' },
        { value: 'crab', label: 'Crab' },
        { value: 'octopus', label: 'Octopus' },
    ]}
    disabled
/>

Energy providers

error / errorMessage


<Autocomplete
    label="Energy providers"
    options={[
        { value: 'lobster', label: 'Lobster' },
        { value: 'prawn', label: 'Prawn' },
        { value: 'crab', label: 'Crab' },
        { value: 'octopus', label: 'Octopus' },
    ]}
    error
    errorMessage="Please select an energy provider"
/>

Energy providers

Please select an energy provider

filterOptions

You can apply further filtering to the options list with this function. This is useful when requesting options from an API, for example, to perhaps filter out empty values. See here for a complete example .


<Autocomplete
    label="Energy providers"
    options={[
        { value: 'lobster', label: 'Lobster' },
        { value: 'prawn', label: 'Prawn' },
        { value: 'crab', label: 'Crab' },
        { value: 'octopus', label: 'Octopus' },
        { value: 'Dismiss me', label: 'Dismiss me' },
        { value: 'Dismiss me too', label: 'Dismiss me too' },
    ]}
    // Return all options that do not contain "Dismiss me"
    filterOptions={(option?: string) => !option.includes('Dismiss me')}
/>

Energy providers

isLoading / loadingText

If you are loading your options from an API, you can use isLoading and loadingText to provide a message to the end user whilst the API call completes. This example simulates a 2s delay on the API call when you type into the box. You can try typing Lobster.


<Autocomplete
    label="Energy providers"
    options={asyncOptions}
    isLoading
    loadingText="Loading energy providers..."
/>

Energy providers

noDataLabel


<Autocomplete
    label="Energy providers"
    options={[]}
    noDataLabel="No options, sorry!"
/>

Energy providers

optional


<Autocomplete
    label="Energy providers"
    options={[
        { value: 'lobster', label: 'Lobster' },
        { value: 'prawn', label: 'Prawn' },
        { value: 'crab', label: 'Crab' },
        { value: 'octopus', label: 'Octopus' },
    ]}
    optional
/>

Energy providers (optional)

theme


<Autocomplete
    label="Energy providers"
    options={[
        { value: 'lobster', label: 'Lobster' },
        { value: 'prawn', label: 'Prawn' },
        { value: 'crab', label: 'Crab' },
        { value: 'octopus', label: 'Octopus' },
    ]}
    theme="secondary500"
/>

Energy providers

value (for controlled input)


const [selectedValue, setSelectedValue] = useState(options[0].label);
 
<Button
    onClick={() => { setSelectedValue(...) }}
>
    {...}
</Button>
 
<Autocomplete
    label="Energy providers"
    options={[
        { value: 'lobster', label: 'Lobster' },
        { value: 'prawn', label: 'Prawn' },
        { value: 'crab', label: 'Crab' },
        { value: 'octopus', label: 'Octopus' },
    ]}
    value={selectedValue}
    onChange={(value) => setSelectedValue(value)}
/>

Energy providers

Event Handlers


<Autocomplete
    onBlur={() => {}}
    onChange={(label, value, reason) => {}}
    onClose={(reason) => {}}
    onHighlightChange={(label, value, reason) => {}}
    onInputChange={(label, value, reason) => {}}
    onItemClick={(label, value, reason) => {}}
    onClear={() => {}}
    onOpen={() => {}}
    ...
/>

Responsiveness


<Autocomplete
    label="Energy providers"
    options={[
        { value: 'lobster', label: 'Lobster' },
        { value: 'prawn', label: 'Prawn' },
        { value: 'crab', label: 'Crab' },
        { value: 'octopus', label: 'Octopus' },
    ]}
    theme={{ base: 'light', lg: 'dark' }}
    fullWidth={{ base: false, lg: true }}
/>

Energy providers

Asyncronous requests from an external API

Please visit this example in our Sandbox . This can be seen live at the bottom of this page .

Full API

Name	Type	Default
`defaultValue`	`string` If set, a default value will be set for the input.
`disabled`	`boolean` If `true`, the component will be disabled and not respond to user interactions	`false`
`dropdownButtonOpenText`	`string` The accessible text to display to screenreaders, labelling the dropdown toggle button when the menu is closed.	`Open`
`dropdownButtonCloseText`	`string` The accessible text to display to screenreaders, labelling the dropdown toggle button when the menu is open.	`Close`
`error`	`boolean` If `true`, the component will have error styling set.	`false`
`errorMessage`	`string` If set, the `ErrorMessage` component will be rendered below the input with this text.
`fullWidth`	`ResponsiveVariant<boolean>` If `true`, the input will take up the full width of its container.
`id`	`string` An accessible ID for the input element. If not provided, one will be generated internally.
`name`	`string` The field name used on the POST request when the form is submitted.
`noDataLabel`	`string` The text to display when the user has entered a search term, but there are no matching options.	`'No options'`
`onBlur`	`() => void` Callback fired whenever the input element loses user focus.
`onChange`	`(label: string \| null, value: string \| null, reason: AutocompleteChangeReason) => void` Callback fired whenever the selected option changes. `label` The label of the selected option, or `null` if no option is selected. `value` The value of the selected option, or `null` if no option is selected. `reason` The reason for the change, which can be one of: `selectOption`: The user selected an option. `clear`: The user cleared the selection.
`onClose`	`(reason: AutocompleteCloseReason) => void` Callback fired whenever the combobox menu is closed. `reason` The reason the menu was closed, which can be one of: `toggleInput`: The user toggled the input. `escape`: The user pressed the escape key. `selectOption`: The user selected an option. `blur`: The input lost focus. `toggleButton`: The user clicked the toggle button.
`onHighlightChange`	`(label: string \| null, value: string \| null, reason: AutocompleteHighlightChangeReason) => void` Callback fired whenever the highlighted menu option changes. `label` The label of the highlighted option, or `null` if no option is highlighted. `value` The value of the highlighted option, or `null` if no option is highlighted. `reason` The reason for the highlight change, which can be one of: `keyboard`: The user navigated using the keyboard. `mouse`: The user navigated using the mouse. `auto`: The highlight was set automatically.
`onInputChange`	`(label: string \| null, value: string \| null, reason: AutocompleteInputChangeReason) => void` Callback fired whenever the input value changes. `label` The label of the input, or `null` if no label is set. `value` The current value of the input, or `null` if the input is empty. `reason` The reason for the input change, which can be one of: `input`: The user typed in the input. `reset`: The input was reset to its default value. `clear`: The user cleared the input.
`onItemClick`	`(label: string \| null \| undefined, value: string \| null \| undefined, reason: string) => void` Callback fired whenever a customer explicitly clicks on a dropdown item. `label` The label of the clicked option, or `null` if no option is clicked. `value` The value of the clicked option, or `null` if no option is clicked. `reason` The reason for the click, which is always `'selectOption'` when this callback is called.
`onClear`	`() => void` Callback fired whenever the clear icon is clicked on the input.
`onOpen`	`() => void` Callback fired whenever the combobox menu is opened.
`options`	`AutocompleteOption[]` The options to display in the Autocomplete dropdown. Each option should have a `label` and `value` property.
`label`	`string` The label to display inside the TextField.
`optional`	`boolean` Add an optional flag to the label for this field (controlled by https://coral-oe.vercel.app/?path=/docs/guides-configuration—docs#overrides-optional-indicator optionalIndicator). This should be set to true if you have set this field to be optional in your validation schema.	`false`
`theme`	`ResponsiveVariant<"secondary500" \| "base100">` The colourway applied to this component.
`value`	`string \| null` `value` should be supplied by the parent component to control the value of the Autocomplete input.
`isLoading`	`boolean` If `true`, the Autocomplete will display a loading state, which will disable the input and show a spinner.
`loadingText`	`string` The text to display when the Autocomplete is in a loading state.
`filterOptions`	`(option?: string \| undefined, inputValue?: string \| undefined) => boolean` A function that filters the options list based on the supplied option and input value.

Design

Good to know

Choose an auto-complete if you have a large amount of data you need the user to select from quickly and easily. It should present a list of options, and also save time by providing predictions as they begin to type, that match the data available.

Why don’t we indicate mandatory fields?

It is a better user experience when forms are explicit about optional fields by labelling them so, that way the user can be reassured they can proceed without completing it. Therefore in Coral our mandatory fields are the default and optional fields are marked as such.

What is the difference between an auto-complete and an accordion?

The accordion will push down the content, while the auto-complete lays over the content, this content is also selectable.

Component breakdown

Corner radius: 12px
Border: 2px
Input text: Body 1
Label container: Caption text
Horizontal padding: 16px | Vertical padding: 16px