JavaScript Data Grid MultiSelect cell type

JavaScript Data GridMultiSelect cell type

Collect user input with a list of multiple-selection choices, by using the MultiSelect cell type.

On this page

Overview

The MultiSelect cell type is designed for scenarios where you need to save and manage a list of values within a single cell. With this cell type, users can open a dropdown menu containing all available options and select any number of values, rather than being limited to just one.

Once selections are made, the values are stored in the table's source data as an array associated with that particular cell. This approach provides both flexibility and clarity when working with datasets that require multiple values per field.

For a clear visual representation, the MultiSelect renderer displays each selected value as an individual, removable chip within the cell. This makes it easy for users to see exactly which values are selected at a glance and to remove any item with a single action if needed.

The list of selectable options (source property) can be provided in two formats:

  • An array of values
  • An array of objects with key and value properties

The source option

The source option can be provided in two formats:

Array of values

You can provide the source option as an array of values that will be used as the MultiSelect options.

    Array of objects

    You can provide the source option as an array of objects with key and value properties. The value property will be used as the MultiSelect's option label, while the entire object will be used as the value saved to the cell's source data.

      Keyboard navigation

      The MultiSelect editor is a dropdown with selectable items. You can select items by clicking them or by using the keyboard:

      When the dropdown opens, the initial focus depends on the searchInput option: if filtering is enabled, the search input is focused by default; if filtering is disabled, the first item in the list is focused.

      • Arrow keys – Move the focus between items in the dropdown list. When the search input is visible, use the down arrow to move focus from the search input into the list, and the up arrow to move focus back into the search input.
      • SPACE or ENTER – Toggle the selection of the focused item. The behavior depends on the enterCommits option:
        • When enterCommits is true (default): ENTER closes the editor and commits the selection; SPACE toggles the focused item's selection.
        • When enterCommits is false: ENTER toggles the focused item's selection; SPACE has no effect.

      Each selection (or deselection) immediately updates the underlying cell data.

      Other options

      The MultiSelect cell type provides several configuration options to tailor its behavior:

      • allowEmpty – Allows empty cell value to pass validation. This is set to true by default.
      • placeholder – Sets placeholder text that's rendered in the cell when the cell is empty.
      • visibleRows – Defines the maximum number of visible rows in the dropdown menu.
      • maxSelections – Determines the maximum number of items that can be selected.
      • sourceSortFunction – A custom sort function to order the dropdown entries.
      • enterCommits – Controls whether pressing the ENTER key closes the editor and commits the selection.
      • searchInput – Toggles the visibility of the search input inside the dropdown.
      • filteringCaseSensitive – When set to true, the dropdown's search filtering is case sensitive.

      These options allow you to modify the MultiSelect cell type's appearance, usability, and behavior to better fit your specific needs.

      The demo below showcases some the options in an interactive example.

        API methods

        When working with object-based MultiSelect data, you can use methods like getSourceData(), getSourceDataAtCell(), getSourceDataAtRow() etc., to get the data array in its original object format with both key and value properties. The getData() method will return only the value property's value in the array.

        TIP

        Note: When the source option is declared as an array of key + value objects, the data in the edited cell should also be an array with key + value objects.