The dropdown input allows users to select a value from a customizable list of options:
The options prop can accept three different formats of values:
value and label keys (see example above)['A', 'B', 'C']{ a: 'A', b: 'B', c: 'C' }If you assign options as an empty array, the input will be rendered in a disabled state.
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:
Unlike native select elements, the dropdown input allows you to customize the options list with markup.
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:
If you only want to customize the display of the selected option, use the selection slot:
Instead of passing a static list of options 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.
Let's say we had an API endpoint that returned all the options we needed for a given dropdown input. Here is an example of how we could write the dropdown input to load options from a single request:
In the example above, we are assigning the options prop to the loadHorrorMovies function. After the request, we're iterating over the results to ensure that we return an array of objects with explicit value and label properties.
What about loading options from an API where you need to be able to make multiple requests to perform pagination? When a function is set to the options prop it is passed FormKit node's context object as an argument. Within this context object are 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:
In the above example, we are calling hasNextPage when we determine there are more pages to load. When this is done, FormKit appends a Load more option at the end of the rendered options list and automatically increments its page property. When the user selects the Load more option, the function assigned to the options prop is called again, and the process repeats.
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, 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:
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.
Instead of using the optionLoader prop to rehydrate values that are not in the options list, you can use the optionLoader to perform a look-up to fetch additional data. In this example, after selecting an option, we are going to perform a look-up to load the selected option's movie review:
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:
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:
When using the dropdown with static options, FormKit's dropdown also comes with a unique feature called overscroll. In this example, we'll see what the behavior is when setting overscroll to true:
| Prop | Type | Default | Description |
|---|---|---|---|
| options | any | [] | The list of options the user can select from. |
| load-on-scroll | boolean | false | When set to `true`, the dropdown will try loading more options based on the end-user`s scroll position |
| option-loader | function | null | Used for hydrating initial value, or performing an additional request to load more information of a selected option. |
| empty-message | string | undefined | Renders a message when there are no options to display. |
| Show universal props | |||
| config | Object | {} | Configuration options to provide to the input’s node and any descendent node of this input. |
| delay | Number | 20 | Number of milliseconds to debounce an input’s value before the commit hook is dispatched. |
| dirtyBehavior | string | touched | Determines how the "dirty" flag of this input is set. Can be set to touched or compare — touched (the default) is more performant, but will not detect when the form is once again matching its initial state. |
| errors | Array | [] | Array of strings to show as error messages on this field. |
| help | String | '' | Text for help text associated with the input. |
| id | String | input_{n} | The unique id of the input. Providing an id also allows the input’s node to be globally accessed. |
| ignore | Boolean | false | Prevents an input from being included in any parent (group, list, form etc). Useful when using inputs for UI instead of actual values. |
| index | Number | undefined | Allows 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. |
| label | String | '' | Text for the label element associated with the input. |
| name | String | input_{n} | The name of the input as identified in the data object. This should be unique within a group of fields. |
| parent | FormKitNode | contextual | By default the parent is a wrapping group, list or form — but this props allows explicit assignment of the parent node. |
| prefix-icon | String | '' | Specifies an icon to put in the prefixIcon section. |
| preserve | boolean | false | Preserves the value of the input on a parent group, list, or form when the input unmounts. |
| preserve-errors | boolean | false | By 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-schema | Object | {} | An object of section keys and schema partial values, where each schema partial is applied to the respective section. |
| suffix-icon | String | '' | Specifies an icon to put in the suffixIcon section. |
| type | String | text | The type of input to render from the library. |
| validation | String, Array | [] | The validation rules to be applied to the input. |
| validation-visibility | String | blur | Determines when to show an input's failing validation rules. Valid values are blur, dirty, and live. |
| validation-label | String | {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-rules | Object | {} | Additional custom validation rules to make available to the validation prop. |
| value | Any | undefined | Seeds the initial value of an input and/or its children. Not reactive. Can seed entire groups (forms) and lists.. |
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.
Below is the inner options list (listbox) structure from the diagram above:
| Section-key | Description |
|---|---|
| selector | The selector section is a button element that opens the dropdown options list. |
| selection | Contains the selected option. |
| listitem | A list item element that contains the option section. |
| option | A div that contains the option content. |
| listbox | The listbox section is a ul element that contains the options list. |
| dropdownWrapper | Wraps the listbox section. A div that handles scrolling the listbox. |
| optionLoading | A span element that is conditionally rendered within the selected option when loading is occurring. |
| loaderIcon | An element for outputting an icon in the selector element when loading is occurring. |
| selectIcon | An element for outputting an icon in the selector element when the dropdown is closed. |
| selectedIcon | An element for outputting an icon next to the selected option when inside the listbox. |
| loadMore | A list item element that is conditionally rendered at the bottom of the options list when there are more pages to load. |
| loadMoreInner | A span element that acts as a wrapper for the loaderIcon within the loadMore section. |
| emptyMessage | A list item element that is conditionally rendered when there are no options to display. |
| emptyMessageInner | A span element that acts as a wrapper for the emptyMessage section. |
| Show universal section keys | |
| outer | The outermost wrapping element. |
| wrapper | A wrapper around the label and input. |
| label | The label of the input. |
| prefix | Has no output by default, but allows content directly before an input element. |
| prefixIcon | An element for outputting an icon before the prefix section. |
| inner | A wrapper around the actual input element. |
| suffix | Has no output by default, but allows content directly after an input element. |
| suffixIcon | An element for outputting an icon after the suffix section. |
| input | The input element itself. |
| help | The element containing help text. |
| messages | A wrapper around all the messages. |
| message | The element (or many elements) containing a message — most often validation and error messages. |