Theme

Autocomplete

View pricing →

Pro installation quickstart 🚀

The autocomplete input allows you to search through a list of options.

The options prop can accept three different formats of values:

  • An array of objects with value and label keys (see example above)
  • An array of strings ['A', 'B', 'C']
  • An object literal with key-value pairs { a: 'A', b: 'B', c: 'C' }
  • A function that returns any of the above
Empty options

If you assign options as an empty array, the input will be rendered in a disabled state.

Basic examples

Single-select

By default, the autocomplete input will render in single-select mode:

Load live example

Multi-select

By setting the multiple prop the autocomplete input will render in multi-select mode:

Load live example
Multi-select input value

Notice in the example above that because the multiple prop is set, the value prop must be an array.

Filtering

The autocomplete input will filter options with its own internal search function. You can replace this search function by providing the filter prop a function of your own. Your function will receive two arguments, the option being iterated over and the current search value:

Load live example

Dynamic options

Instead of passing a static list to the options prop, you can assign it to a function. Doing so is useful when you need to load options from an API or another source.

Search parameter

In this example, we'll assign the options prop the searchMovies function. By doing so, searchMovies will receive the context object as an argument. Within this context object is the search property, which is the current search value. To perform our search, we'll use the search value as the query parameter for our API request:

Load live example

Page and hasNextPage parameters

A likely scenario you'll encounter is needing to search through a paginated API. This can be done by referencing the same context object as before. Within this object, we can utilize the page and hasNextPage properties. The page property is the current page number, and the hasNextPage property is a function to be called when there are more pages to load:

Load live example

Option loader

Rehydrating values

FormKit's autocomplete input also provides an optionLoader prop that allows you to rehydrate values that are not in the options list. In this example, we'll provide the autocomplete an initial value (a movie ID), and assign the optionLoader to a function that will make a request to the API to get the movie:

Load live example

Notice in the example above that the optionLoader function is passed two arguments: the value of the selected option (in this case, the movie ID) and the cachedOption. The cachedOption prop is used for preventing unnecessary lookups. If the cachedOption is not null it means that the selected option has already been loaded, and you can return the cachedOption directly.

Loading Style

Instead of requiring your users to click the Load more button to load additional options, you can set the loadOnScroll prop to true, which will paginate options as you scroll to the bottom of the options list.

Load on created

If you would rather load options when the autocomplete is created, you can set the load-on-created prop to true, and our function, loadCurrentlyPopularMovies will be called without the user needing to expand the listbox:

Load live example

Option appearance

Option slot

The autocomplete input allows you to customize the look and feel of each option by using the option slot. In this example, we are using the option slot to display each option's asset; logo and name:

Load live example

Selection appearance

The autocomplete input allows you to customize the look and feel of the selected option.

Selection appearance prop

The autocomplete input allows you to customize the look and feel of the selected option by using the selection-appearance prop. For either the single-select or multi-select autocomplete, you can set the selection-appearance prop to text-input (default) or option:

Load live example

Selection slot

If you only want to customize the display of the selected option, set the selection appearance to option.

Load live example

Behavioral props

Empty message

The autocomplete input, by default, will not expand the listbox when no search results are found while filtering. You can change this behavior by assigning the empty-message prop a message to display when no results are found:

Load live example

Close on select

If you would like the listbox to remain expanded after selecting a value, you can set close-on-select to false.

Load live example

Reload on commit

If you want the options to be reloaded when the user commits a selection, use the reload-on-commit prop:

Load live example

Open on click

To enable opening the autocomplete's listbox on click of its search input, set the open-on-click prop to true:

Load live example

Open on focus

If you would like to open the autocomplete's listbox anytime the input is clicked, set the open-on-focus prop to true:

Load live example
Open on focus vs Open on click

If open-on-focus is used, open-on-click will implicitly be set.

Clear search on open

For single-select autocompletes only, if you would like to clear the search input when the listbox is opened, set the clear-search-on-open:

Load live example

Selection removable

For a single-select autocomplete, you can set the selection-removable prop. When set to true, a remove button will be displayed next to the selected option. This prop is by default set to true for autocompletes with selection appearance of option.

Single select only

The selection-removable prop cannot be used for multi-selects.

Load live example

Open on remove

If you want the listbox to expand when an selection is removed, use the open-on-remove prop:

Load live example

Max

If you would like to limit the number of options that can be selected, you can use the max prop:

Load live example

Full example

Now let's combine what we've learned so far by leveraging the option slot for custom markup, and setting the options prop to a function that will return pages of movies from an API:

Load live example

Props & Attributes

PropTypeDefaultDescription
debouncenumber200Number of milliseconds to debounce calls to an options function.
optionsany[]The list of options the user can select from.
load-on-scrollbooleanfalseWhen set to `true`, the autocomplete will try loading more options based on the end-user`s scroll position
selection-appearancestringtext-inputChanges the way the option label is display.
multiplebooleanfalseAllows for multiple selections.
open-on-clickbooleanfalseThe autocomplete is expanded upon focus of the input, as opposed to waiting to expand until a search value is entered.
filterfunctionnullUsed to apply your own custom filter function for static options.
option-loaderfunctionnullUsed for hydrating initial value, or performing an additional request to load more information of a selected option.
empty-messagestringundefinedRenders a message when there are no options to display.
maxnumberundefinedLimits the number of options that can be selected.
open-on-removebooleanfalseWhen the `selection-removable` prop is set to `true`, the autocomplete will not open after the selected value is removed. You can change this behavior by setting the `open-on-remove` prop to `true`.
open-on-focusbooleanfalse
options-appearancestringundefinedFor multi-select autocompletes, this prop allows you to customize the look and feel of the selected options. Possible values are `default` (the default) or `checkbox`.
always-load-on-openbooleantrueDetermines whether the autocomplete should always load its options when opened or whether it should reference the options that were previously found when opening.
load-on-createdbooleanfalseWhen set to `true`, the autocomplete will load the options when the node is created.
clear-search-on-openbooleanfalseWhen set to `true`, the search input will be cleared when the listbox is opened.
maxnumber | stringundefinedIf you would like to limit the number of options that can be selected, you can use the `max` prop (applies only to multi-select).
popoverbooleanfalseRenders the input's listbox using the browser Popover API.
Show Universal props
configObject{}Configuration options to provide to the input’s node and any descendent node of this input.
delayNumber20Number of milliseconds to debounce an input’s value before the commit hook is dispatched.
dirtyBehaviorstringtouchedDetermines how the "dirty" flag of this input is set. Can be set to touched or comparetouched (the default) is more performant, but will not detect when the form is once again matching its initial state.
errorsArray[]Array of strings to show as error messages on this field.
helpString''Text for help text associated with the input.
idStringinput_{n}The unique id of the input. Providing an id also allows the input’s node to be globally accessed.
ignoreBooleanfalsePrevents an input from being included in any parent (group, list, form etc). Useful when using inputs for UI instead of actual values.
indexNumberundefinedAllows an input to be inserted at the given index if the parent is a list. If the input’s value is undefined, it inherits the value from that index position. If it has a value it inserts it into the lists’s values at the given index.
labelString''Text for the label element associated with the input.
nameStringinput_{n}The name of the input as identified in the data object. This should be unique within a group of fields.
parentFormKitNodecontextualBy default the parent is a wrapping group, list or form — but this props allows explicit assignment of the parent node.
prefix-iconString''Specifies an icon to put in the prefixIcon section.
preservebooleanfalsePreserves the value of the input on a parent group, list, or form when the input unmounts.
preserve-errorsbooleanfalseBy default errors set on inputs using setErrors are automatically cleared on input, setting this prop to true maintains the error until it is explicitly cleared.
sections-schemaObject{}An object of section keys and schema partial values, where each schema partial is applied to the respective section.
suffix-iconString''Specifies an icon to put in the suffixIcon section.
typeStringtextThe type of input to render from the library.
validationString, Array[]The validation rules to be applied to the input.
validation-visibilityStringblurDetermines when to show an input's failing validation rules. Valid values are blur, dirty, and live.
validation-labelString{label prop}Determines what label to use in validation error messages, by default it uses the label prop if available, otherwise it uses the name prop.
validation-rulesObject{}Additional custom validation rules to make available to the validation prop.
valueAnyundefinedSeeds the initial value of an input and/or its children. Not reactive. Can seed entire groups (forms) and lists..

Sections

You can target a specific section of an input using that section's "key", allowing you to modify that section's classes, HTML (via :sections-schema, or content (via slots)). Read more about sections here.

The autocomplete's structure changes depending on a few different scenarios:

  • Whether selection-appearance has been set to text-input (the default) or option.
  • Whether multiple selections are enabled via the multiple attribute.

Selection appearance text-input

View on a larger screen to see this section diagram.

Your favorite athletes
Serena, Pelé
Tiger Pelé
Search for your favorite athletes.
Sorry, that athlete could not be found.

Selection appearance option, single selection

View on a larger screen to see this section diagram.

Your favorite athlete
Pelé
X
Tiger Pelé
Search for your favorite athlete.
Sorry, that athlete could not be found.

Selection appearance option, multiple selection

View on a larger screen to see this section diagram.

Your favorite athlete
Tiger Pelé
Pelé
X
Search for your favorite athlete.
Sorry, that athlete could not be found.

Inner listbox structure

Below is the inner options list (listbox) structure from the diagrams above:

View on a larger screen to see this section diagram.

Section-keyDescription
selectorThe selector section is a button element that opens the dropdown options list.
selectionsContains individual selection sections.
selectionContains the selected option.
listitemA list item element that contains the option section.
optionA div that contains the option content.
listboxThe listbox section is a ul element that contains the options list.
dropdownWrapperWraps the listbox section. A div that handles scrolling the listbox.
optionLoadingA span element that is conditionally rendered within the selected option when loading is occurring.
loaderIconAn element for outputting an icon in the selector element when loading is occurring.
selectIconAn element for outputting an icon in the selector element when the dropdown is closed.
loadMoreA list item element that is conditionally rendered at the bottom of the options list when there are more pages to load.
loadMoreInnerA span element that acts as a wrapper for the loaderIcon within the loadMore section.
removeSelectionA button element used for removing a specific selection.
closeIconAn element for outputting an icon within the removeSelection button.
listboxButtonA button element that is used to open the dropdown.
emptyMessageA list item element that is conditionally rendered when there are no options to display.
emptyMessageInnerA span element that acts as a wrapper for the emptyMessage section.
Show Universal section keys
outerThe outermost wrapping element.
wrapperA wrapper around the label and input.
labelThe label of the input.
prefixHas no output by default, but allows content directly before an input element.
prefixIconAn element for outputting an icon before the prefix section.
innerA wrapper around the actual input element.
suffix