Pro installation quickstart 🚀

    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:

    Load Live Example

    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

    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:

    Load Live Example

    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.

    Load Live Example

    Slots

    Just like the Dropdown 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:

    Load Live Example

    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.

    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

    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

    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:

    Load Live Example

    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:

    Load Live Example

    Props & Attributes

    Prop Type Default Description
    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 dropdown will try loading more options based on the end-user`s scroll position
    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.
    allow-new-valuesbooleanfalseAllows end-user to enter a new value that does not exist within the options list.
    disable-drag-and-dropbooleantrueDisabled end-user from sorting tags by dragging and dropping.
    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.
    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..
    Section-key Description
    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.
    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.