Dropdown

• Basic example
• Defining options
• Empty message
• Slots
  • Option slot
  • Selection slot
• Loading options
  • Single request
  • Multiple pages
  • Option loader
  • Load on scroll
• Full example
• Overscroll
• Props & Attributes
• Sections
  • Outer structure
  • Inner listbox structure

Basic example

The dropdown input allows users to select a value from a customizable list of options:

Defining 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 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:

Slots

Unlike native select elements, the dropdown input allows you to customize the options list with 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:

Selection slot

If you only want to customize the display of the selected option, use the selection slot:

Loading options

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.

Single request

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.

Multiple pages

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.

Option loader

Rehydrating values

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.

Fetching additional data

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:

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:

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:

Overscroll

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:

Props & Attributes

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.

Outer structure

Inner listbox structure

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