Theme

Pro installation quickstart 🚀

The dropdown input allows users to select a value from a list of options. Unlike native select elements, the dropdown input allows you to customize both its appearance and behavior.

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

The dropdown input will render in single-select mode by default.

Load live example

Multi-select

Dropdown inputs with the prop multiple set 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.

Dynamic options

Instead of passing a static list to the options prop, options can be assigned dynamically.

In this example, the function, loadHorrorMovies, makes a request to the API for TMDB to load a list of horror movies. Assigning the function to the options prop will load the options when the end-user opens the listbox.

Load live example

Always load on open

By default the dropdown will only load options asynchronously once (upon the listbox being expanded). Setting the prop always-load-on-open will cause the dropdown to load options every time the listbox is expanded.

Load live example

Load on created

The prop load-on-created will cause the dropdown to load options as soon as it is created.

Load live example

Pagination

A function assigned the options prop will be passed two arguments: page and hasNextPage. The page argument indicates the current page number, and hasNextPage is a callback function that indicates whether there are more pages to load.

Load live example

Load on scroll

If you would rather allow the user to load more options without having to click the Load more option at the bottom of the options list, you can set the load-on-scroll prop to true, and our function, loadCurrentlyPopularMovies will be called again:

Load live example

Option loader

FormKit's dropdown input also provides an optionLoader prop that allows you to rehydrate values that are not in the options list. In this example the dropdown is provided an initial value (two movie IDs). The optionLoader function is called for each value that is not in the options list.

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.

Option appearance

Unlike native select elements, the dropdown input can be customized via. markup.

Option slot

The dropdown 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 dropdown input allows you to customize the look and feel of the selected option(s).

Selection appearance prop

When using the dropdown input as a multi-select, you can customize the look and feel of the selected options by setting the selection-appearance prop to either truncate (the default) or tags.

Load live example

Selection slot

If you only want to customize the display of the selected option, use the selection slot (as opposed to the option slot mentioned above):

Load live example
Single-select and tags only

The selection slot does not exist on the multi-select dropdown with selection appearance truncate.

Behavioral props

The following props allow you to customize the behavior of the dropdown input.

Empty Message

The dropdown input, by default, will be rendered in a disabled state if no options are passed. Optionally, you may pass the empty-message prop a message to display when no options are available:

Load live example

Selection Removable

If you would like to allow users to remove the selected value, set the selection-removable prop to true. This will render a close icon next to the selected value:

Single select only

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

Load live example

Open on remove

By default, when the selection-removable prop is set to true, the dropdown will not open after the selected value is removed. You can change this behavior by setting the open-on-remove prop to true:

Load live example

Close on select

By default, when the multiple prop is set, the dropdown will not close after an option is selected. You can change this behavior by setting the close-on-select prop to true:

Load live example

Open on focus

If you would like expand the listbox as soon as the dropdown input is focused, you can use the open-on-focus prop:

Load live example

Overscroll

When using the dropdown with static options, FormKit's dropdown also comes with a feature called overscroll. Setting the behavior prop to overscroll will render the listbox directly over the input to maximize the available size for the list:

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

Props & Attributes

PropTypeDefaultDescription
optionsany[]The list of options the user can select from.
load-on-scrollbooleanfalseWhen set to `true`, the dropdown will try loading more options based on the end-user`s scroll position
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.
selection-appearancestringtruncateFor multi-select dropdowns, this prop allows you to customize the look and feel of the selected options. Possible values are `truncate` (the default) or `tags`.
selection-removablebooleanfalseFor single-select dropdowns, this prop allows you to remove the selected value.
open-on-removebooleanfalseWhen the `selection-removable` prop is set to `true`, the dropdown will not open after the selected value is removed. You can change this behavior by setting the `open-on-remove` prop to `true`.
close-on-selectbooleanfalseWhen the `multiple` prop is set, the dropdown will not close after an option is selected. You can change this behavior by setting the `close-on-select` prop to `true`.
open-on-focusbooleanfalseIf you would like expand the listbox as soon as the dropdown input is focused, you can use the `open-on-focus` prop.
options-appearancestringundefinedFor multi-select dropdowns, this prop allows you to customize the look and feel of the selected options. Possible values are `default` (the default) or `checkbox`.
multiplebooleanfalseWhen set to `true`, the dropdown will allow the user to select multiple options.
behaviorstringundefinedRenders the listbox directly over the input to maximize the available size for the list.
always-load-on-openbooleanfalseDetermines whether the dropdown 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 dropdown will load the options when the node is created.
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).
deselectbooleantrueWhen set to `false`, the end-user cannot deselect a selected option form the listbox.
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.

Selector structure

View on a larger screen to see this section diagram.

Select t-shirt color
Select t-shirt color
×
Turn sound effects on and off.
Something wrong happened.

Listbox structure

View on a larger screen to see this section diagram.

Selection structure

View on a larger screen to see this section diagram.

Gray

View on a larger screen to see this section diagram.

Gray
Blue
+1

View on a larger screen to see this section diagram.

Gray
×
Blue
×
Section-keyDescription
selectorThe selector section is a button element that opens the dropdown options list.
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.
selectedIconAn element for outputting an icon next to the selected option when inside the listbox.
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.
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.
tagsWrapperA div element that wraps the tags section.
tagsA div element that contains the tags.
tagWrapperA div element that wraps the tag.
tagA div element that contains the tag label and removeSelection section.
tagLabelA span element that contains the tag label.
removeSelectionA span element that contains the removeSelection icon.
selectorSelectionsWrapperA div element that wraps the selectorSelections section.
selectorSelectionsA div element that contains the selectorSelectionsItem sections.
selectorSelectionsItemA div element that contains the selectorSelectionsItem content.
truncationCountA div element that contains the truncationCount content.
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.
suffixHas no output by default, but allows content directly after an input element.
suffixIconAn element for outputting an icon after the suffix section.
inputThe input element itself.
helpThe element containing help text.
messagesA wrapper around all the messages.
messageThe element (or many elements) containing a message — most often validation and error messages.

Accessibility

All FormKit inputs are designed with the following accessibility considerations in mind. Help us continually improve accessibility for all by filing accessibility issues here:

Semantic markupAria attributesKeyboard accessibleFocus indicatorsColor contrast with the provided themeAccessible labels, help text, and errors
Section KeyAttributeDefaultDescription
selectortabindex0Prioritizes keyboard focus order by setting it to 0
aria-haspopuplistboxSignals the presence of a pop-up listbox triggered by interaction.
aria-expandedIndicates whether the dropdown element is currently expanded or collapsed.
aria-controlsLinks this element to the ID of the listbox element.
aria-describedByAssociate this element with descriptive text from another element.
placeholderaria-hiddentrueMakes this element not exposed to the accessibility API when no placeholder exists.
removeSelectiontabindex-1Prioritizes keyboard focus order by setting it to -1
aria-controlsLinks this element to the ID of the input element.
selectionsaria-livepoliteAnnouces to screen readers that this element was dynamically updated without interrupting the current task.
aria-hiddentrueMakes this element not exposed to the accessibility API.
selectionsItemaria-hiddentrueMakes this element not exposed to the accessibility API when last visible index and index are greater than last visible index.
tagWrappertabindex0Prioritizes keyboard focus order by setting it to 0
tagtabindex0Prioritizes keyboard focus order by setting it to 0
tagsWrapperaria-livepoliteAnnouces to screen readers that this element was dynamically updated without interrupting the current task.
Show Universal section key
labellabelforAssociates the label to an input element. Users can click on the label to focus the input or to toggle between states.
inputinputdisabledDisables an HTML element, preventing user interaction and signaling a non-interactive state.