The MultiLevelSelect kit renders a multi leveled select dropdown based on data from the user. treeData is a required prop that is expected to contain the data in the form of an array of objects. See code snippet for an example data array.
For the React version of the kit, the onSelect prop returns an array of objects. This array contains all checked items irrespective of whether it is a parent, child or grandchild. Open the console on this example and check and uncheck checkboxes to see this is action!
For the Rails version of the kit, there is no onselect. The form submits as a array of strings, following the typical rails pattern of utilizing hidden inputs. The strings are the values of the selected items' ids. For example, ["103", "106", "107"].
You can pass react-hook-form props to the MultiLevelSelect kit. Check your console to see the full data selected from this example.
Optionally enable the single variant to replace checkboxes with radios so the input accepts and returns only a single selection.
Dynamically control your selectable options by passing hideRadio: true to any node within your tree data to omit that node's radio selector. In this example we've hidden all radios except ultimate children (nodes without descendants).
The returnAllSelected or return_all_selected prop can be used when users want data on all checked nodes from the dropdown, irrespective of whether it is a parent or child node.
NOTE: This variant also does not automatically uncheck the parent when any of the child nodes are unchecked. returnAllSelected is set to false by default.
NOTE: For larger trees that may return many pill selections, you can optionally set input_display: "none"(for Rails) or inputDisplay = "none"(for React) to hide all pills within the input.
selected_ids is an optional prop that accepts an array of ids and controls the selected state of the tree nodes that match the values passed. When used within react-hook-form, this prop can be used to manage the selected state of any ids passed to it.
Items that include checked:true on the treeData itself will also be selected on page load, even without being passed to selectedIds.
When an item is marked as checked on page load by any means, the dropdown will expand to show the checked items for easier accessibility.
Change the form pill color by passing the optional pillColor prop. Product, Data, and Status colors are available options. Check them out here in the Form Pill colors example.
The MultiLevelSelect also provides a subcomponent structure which can be used to render children to the right of the Checkboxes and their labels. As seen in the code snippet below, these children have access to the current item being iterated over which can be used for conditional rendering.
The MultiLevelSelect subcomponent structure is also available in the 'Single Select' variant. In this variant, the children will be rendered to the right of the Radios and their labels.
To disable individual items in the treeData, include disabled:true within the object on the treeData that you want disabled. See the code snippet below for an example of how to do this.
If a parent is selected, the parent will be returned in the selected items list, even if it has disabled children.
individual items can also be disabled by including the disabled:true within the object on the treeData for the returnAllSelected/return_all_selected variant. As noted above, this variant will return data on all checked nodes from the dropdown, irrespective of whether it is a parent or child node.
For the default variant, disabling the parent item will automatically disable it's children as well.
If you want to be able to disable a parent WITHOUT disabling it's children, use the returnAllSelected/return_all_selected variant.
For the returnAllSelected/return_all_selected variant, disabling the parent item will NOT automatically disable it's children since this version allows you to select a parent even if all children are unselected.
You can manually pass disabled:true to any and all children of a disabled parent if you want to do so.
