Tree Select

A lightweight (~3kb gzipped), zero-dependency UI control that transforms <select> or <input> elements into interactive hierarchical trees with checkboxes.

Features

• Async data fetching
• Customizable depth for collapsing, checkboxes and values
• Parent/child selection propagation
• Supports both input and select HTML elements
• Built in functionalities like search, shift+select, clear
• Tailwind support by injectable classNames
• TypeScript support

Installation

npm install @wesleydebruijn/tree-select

Usage

Basic Usage

<input type="text" id="tree-select" value="1,2" />
<!-- or -->
<select id="tree-select" multiple>
  <option value="1" selected>1</option>
  <option value="2" selected>2</option>
  <option value="3">3</option>
</select>

import { TreeSelect } from 'tree-select';

const settings = {
  data: [
    {
      id: '1',
      name: 'Parent 1',
      children: [
        { id: '1-1', name: 'Child 1-1' },
        { id: '1-2', name: 'Child 1-2' },
      ],
    },
    {
      id: '2',
      name: 'Parent 2',
      children: [
        { id: '2-1', name: 'Child 2-1' },
        { id: '2-2', name: 'Child 2-2' },
      ],
    },
  ],
  text: {
    search: 'Search items...',
    selected: 'items selected',
    loading: 'Loading...',
  },
};

const element = document.getElementByid('tree-select');
const treeSelect = new TreeSelect(element, settings);
// or
const treeSelect = new TreeSelect('#tree-select', settings);

Advanced Configuration

const treeSelect = new TreeSelect('#tree-select', {
  // UI state
  mode: 'vertical',
  open: false,
  collapsible: true,
  searchable: true,
  clearable: true,
  results: false,

  // Data configuration
  data: [...], // Tree data
  dataSrc: 'api/tree-data.json', // Or load from URL

  // Depth settings
  depthCollapsible: 0, // Depth at which items become collapsible
  depthCollapsed: 0,   // Depth at which items are collapsed by default
  depthCheckboxes: 0,  // Depth at which checkboxes appear
  depthValues: 'last', // Use 'last' or number to specify which depth values are used

  // Text customization
  text: {
    search: 'Search...',
    selected: 'selected',
    loading: 'Loading...'
  },

  // HTML customization
  focus: 'focus',
  disabled: 'disabled',
  html: {
    wrapper: { className: 'custom-wrapper', data: { value: "custom" } },
    control: { className: 'custom-control' },
    // ... customize other elements
  },

  // Event handlers
  onOpen: () => console.log('Opened'),
  onClose: () => console.log('Closed'),
  onSelect: (selected) => console.log('Selected:', selected),
  onSearch: (search) => console.log('Searching:', search),
  onLoad: (data) => console.log('Data loaded:', data),
  onClear: () => console.log('Cleared')
});

Methods

// Open the dropdown
treeSelect.open();

// Close the dropdown
treeSelect.close();

// Load data & HTML tree to the DOM
treeSelect.load();

// Disable the input & control
treeSelect.disable();

// Enable the input & control
treeSelect.enable();

// Destroy the instance and return to original input/select
treeSelect.destroy();

Data Structure

interface Data {
  id: string | number;
  name: string;
  children?: Data[];
}

Settings

Setting	Type	Default	Description
mode	'vertical' | 'horizontal'	'vertical'	Display tree vertically or horizontally
open	boolean	false	Whether dropdown should be open initially
clearable	boolean	true	Whether to show clear button
searchable	boolean	true	Whether to show search input
collapsible	boolean	true	Whether nodes can be collapsed
results	boolean	false	Whether to show selected items on side
delimiter	string	','	Delimiter for input values
depthCollapsible	number	0	Depth at which nodes become collapsible
depthCollapsed	number	0	Depth at which nodes start collapsed
depthCheckboxes	number	0	Depth at which checkboxes start appearing
depthValues	number | 'last'	'last'	Depth at which values start being collected
data	Data[]	undefined	Initial data array
dataSrc	string	undefined	URL to fetch data from
focus	string	'focus'	Class name applied when dropdown is focused
text	object	{}	Text customization options
text.heading	string	undefined	Text shown in dropdown heading
text.selected	string	'selected'	Text shown after selected count
text.loading	string	'Loading...'	Text shown while loading
text.search	string	'Search...'	Placeholder text for search input
html	object	{}	HTML elements customization
onLoad	function	undefined	Callback when data is loaded
onOpen	function	undefined	Callback when dropdown opens
onClose	function	undefined	Callback when dropdown closes
onClear	function	undefined	Callback when selection is cleared
onSearch	function	undefined	Callback when search is performed
onSelect	function	undefined	Callback when items are selected/deselected

HTML Elements

Element	Class Name	Description
wrapper	tree-select-wrapper	Container element wrapping the entire component
control	tree-select-control	Main control element showing selected count
dropdown	tree-select-dropdown	Dropdown container that appears when opened
clear	tree-select-clear	Clear button to remove all selections
search	tree-select-search	Search input field for filtering items
loading	tree-select-loading	Loading indicator shown while data loads
listContainer	tree-select-list-container	Container for all lists of the tree
list	tree-select-list	Container for a list of the three
item	tree-select-item	Individual item in the tree
checkbox	tree-select-checkbox	Checkbox input for selecting items
collapse	tree-select-collapse	Toggle button for expanding/collapsing nodes
label	tree-select-label	Label container for item text and controls
labelSpan	tree-select-label-span	Text element within item label
children	tree-select-children	Container for child items
result	tree-select-result	Individual item of selected item in the tree

Development

To set up the development environment:

1. Clone the repository:

   git clone https://github.com/@wesleydebruijn/tree-select.git
   cd tree-select

2. Start the development server:

   cd demo
   npm install
   npm run dev

This will start a Vite development server with hot module reloading. The demo page will be available at http://localhost:5173/tree-select/.