TreeSelect

A hierarchical select control for nested options, categories and tree-based selection workflows.

Import

import { TreeSelect } from "@schukai/monster/source/components/form/tree-select.mjs";

Source

View source code

Package

@schukai/monster

Since

1.9.0

Introduction

The Monster TreeSelect handles hierarchical option sets where a flat dropdown would lose important structure. Use it for categories, nested permissions, product taxonomies or any selection flow with parent-child relationships.

When to use TreeSelect

Use it for nested data: The component preserves hierarchy instead of flattening it away.
Use it when path context matters: Users can understand where a value belongs inside the tree.
Do not use it for short flat lists: A regular select is faster when there is no real hierarchy.

Typical mistakes

Keep the tree understandable. Deeply nested structures without clear labels become hard to scan, even with a good tree control.

Tree Select Simple

In this example, a simple select with a tree is defined. The data structure in this example looks like this:


[
  { "cid": 1, "parentCID": null, "label": "Electronics" },
  { "cid": 2, "parentCID": null, "label": "Fashion" },
  { "cid": 3, "parentCID": null, "label": "Home & Garden" },
  { "cid": 4, "parentCID": null, "label": "Toys & Hobbies" },
  { "cid": 5, "parentCID": 1, "label": "Mobile Phones" },
  { "cid": 6, "parentCID": 1, "label": "Laptops" },
  { "cid": 7, "parentCID": 1, "label": "Cameras" },
  { "cid": 8, "parentCID": 2, "label": "Men's Fashion" },
  { "cid": 9, "parentCID": 2, "label": "Women's Fashion" },
  { "cid": 10, "parentCID": 3, "label": "Furniture" },
  { "cid": 11, "parentCID": 3, "label": "Garden Supplies" },
  { "cid": 12, "parentCID": 3, "label": "Home Decor" },
  { "cid": 13, "parentCID": 10, "label": "Living Room Furniture" },
  { "cid": 14, "parentCID": 10, "label": "Bedroom Furniture" },
  { "cid": 15, "parentCID": 14, "label": "Beds" },
  { "cid": 16, "parentCID": 14, "label": "Wardrobes" },
  { "cid": 17, "parentCID": 4, "label": "Educational Toys" },
  { "cid": 18, "parentCID": 4, "label": "Outdoor Toys" },
  { "cid": 19, "parentCID": 17, "label": "Building Blocks" },
  { "cid": 20, "parentCID": 17, "label": "Science Kits" }
]

In this example, the correct mappings are crucial. The first step is to define what the continuous number (i.e., the ID) in the dataset is. Here, it is the cid. The reference to a parent element is made through the field parentCID. The corresponding label is clearly located in the label field. To assign the label and its value, a template is used. Additional functions can also be applied within this template. The important point here is that the value must be a string. If the JSON contains a number, it can be converted using tostring.

Javascript

import '@schukai/monster/source/components/form/tree-select.mjs';<script type="module">import '@schukai/monster/source/components/form/tree-select.mjs';</script>

HTML

<monster-tree-select
        data-monster-option-url="/assets/examples/categories.json"
        data-monster-option-type="checkbox"
        data-monster-option-mapping-selector="*"
        data-monster-option-mapping-id="cid"
        data-monster-option-mapping-parent="parentCID"
        data-monster-option-mapping-labeltemplate="${label}"
        data-monster-option-mapping-valuetemplate="${cid | tostring}"
></monster-tree-select>

Stylesheet

/** no additional stylesheet is defined **/

Open in playground

Component Design

This component is built using the Shadow DOM, which allows it to encapsulate its internal structure and styling. By using a shadow root, the component's internal elements are isolated from the rest of the webpage, ensuring that external styles or scripts cannot accidentally modify its internal layout or behavior.

Shadow DOM and Accessibility

Since the component is encapsulated within a shadow root, direct access to its internal elements is restricted. This means that developers cannot manipulate or style these elements from outside the component. The Shadow DOM helps maintain consistency in the design and behavior of the component by preventing external interference.

Customizing Through Exported Parts

While the Shadow DOM restricts direct access to the component's internal structure, customization is still possible through exported parts. Specific parts of the component are made accessible for styling by being explicitly marked for export. These exported parts can be targeted and customized using CSS, allowing you to modify the appearance of the component without compromising its encapsulation.

Available Part Attributes

control: This part represents the entire control area of the slider, including navigation buttons and thumbnails. Use this to style the general layout and background of the control panel.

Below is an example of how to use CSS part attributes to customize different parts of the Control.


monster-component::part(control) {
    background-color: #f0f0f0;
    padding: 10px;
}

Explanation of the Example

monster-slider::part(control): Styles the entire control panel, giving it a light background color and some padding.

Accessibility

Accessibility is a key consideration in the design of this component. By following best practices for web accessibility, the component ensures that users of all abilities can interact with it effectively. This includes support for keyboard navigation, screen readers, and other assistive technologies to provide an inclusive user experience.

HTML Structure

<monster-tree-select></monster-tree-select>

JavaScript Initialization

const element = document.createElement('monster-tree-select');
document.body.appendChild(element);

Exported

TreeSelect, formatHierarchicalSelection

Derived from

Select

Options

The Options listed in this section are defined directly within the class. This class is derived from several parent classes, including the CustomElement class. Therefore, it inherits Options from these parent classes. If you cannot find a specific Options in this list, we recommend consulting the documentation of the Select.

Option

Type

Default

Description

mapping.rootReferences

array

['0',

string

mapping.idTemplate=id

string

mapping.parentTemplate=parent

string

mapping.selection

string

mapping.labelTemplate

string

mapping.valueTemplate

mapping.filter

string

The filter function to apply to each node, you can use run: syntax to execute a function, or use call:filterValueOfAttribute:data-my-attribute.

object

formatter

string

formatter.separator=" / "

since
deprecated

Properties and Attributes

The Properties and Attributes listed in this section are defined directly within the class. This class is derived from several parent classes, including the CustomElement class and ultimately from HTMLElement. Therefore, it inherits Properties and Attributes from these parent classes. If you cannot find a specific Properties and Attributes in this list, we recommend consulting the documentation of the Select.

data-monster-options: Sets the configuration options for the collapse component when used as an HTML attribute.
data-monster-option-[name]: Sets the value of the configuration option [name] for the collapse component when used as an HTML attribute.

Methods

The methods listed in this section are defined directly within the class. This class is derived from several parent classes, including the CustomElement class and ultimately from HTMLElement. Therefore, it inherits methods from these parent classes. If you cannot find a specific method in this list, we recommend consulting the documentation of the Select.

Static methods

[instanceSymbol]()2.1.0

Returns

{symbol}

This method is called by the instanceof operator.

getCSSStyleSheet()

Returns

{CSSStyleSheet[]}

getTag()

Returns

{string}

Lifecycle methods

Lifecycle methods are called by the environment and are usually not intended to be called directly.

[assembleMethodSymbol]()

Returns

{TreeSelect}

Other methods

importOptions(data)

Parameters

data {array|object|map|set}: data

Returns

{Select}

Throws

{Error} map is not iterable

Import Select Options from dataset Not to be confused with the control defaults/options

Events

The component emits the following events:

monster-options-set
monster-selected
monster-change
monster-changed

For more information on how to handle events, see the mdn documentation.

The current width of the area is too small to display the content correctly.