Taglist

• Basic example
• Filtering
• Allow new values
• Dynamic options
  • Search parameter
  • Page and hasNextPage parameters
  • Loading Style
  • Option loader
  • Loading Style
  • Load on created
• Tag appearance
• Behavioral props
  • Empty message
  • Max
  • Close on select
  • Reload on commit
  • Open on click
  • Open on focus
  • Open on remove
• Full example
• Props & Attributes

The taglist input allows users to search through a list of options and apply any number of tags. Users can also drag and drop tags to re-order:

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

Basic example

The taglist input allows users to search through a list of options and apply any number of tags. Users can also drag and drop tags to re-order:

Filtering

The taglist 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:

Allow new values

The taglist input, unlike the dropdown or autocomplete inputs, allows you to enter an arbitrary value (a value not in the list of options). This is useful for creating new tags on the fly. To enable this feature, set the allow-new-values prop to true.

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:

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:

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.

Option loader

Rehydrating values

FormKit's taglist 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 taglist 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 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 taglist 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:

Tag appearance

Just like the taglist input or Autocomplete input, the taglist input allows you to utilize slots to customize the look and feel of the options list and the selected option by leveraging the renderless component pattern.

In this example, we are going to use the tag slot to customize the look of the tags:

Behavioral props

Empty message

The taglist 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:

Max

The max prop allows you to limit the number of options that can be selected. When the max limit is reached, the taglist input will disable the listbox:

Close on select

If you would like the taglist's listbox to remain open in between selections, set the close-on-select prop to false:

Reload on commit

If you want the options to be reloaded (with static options, this would filter the options with the value of empty string, and with dynamic options, this would make a request to the options loader with the value of empty string) when the user commits a selection, use the reload-on-commit prop:

Open on click

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

Open on focus

If you would like to open the taglist's listbox anytime its search input is focused, set the open-on-focus prop to true:

Open on remove

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

Full example

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

Props & Attributes