Headless Tree Select

A high-performance, lightweight, and fully customizable tree selection component for React. It handles the complex recursive selection logic, indeterminate states, and expansion management while giving you total control over the UI.

Why Headless?

Most tree-select components come with heavy styles and rigid DOM structures. Headless Tree Select decouples logic from presentation. Whether you're using Tailwind CSS, Styled Components, or plain CSS, you can inject your own components or classes without fighting the library's defaults.

Features

• 🌲 Infinite Depth: Support for deeply nested tree structures.
• ✅ Cascading Selection: Built-in logic for parent-child selection linkage.
• ➖ Indeterminate State: Accurate calculation of partial selection status.
• 🎨 Granular Customization: Override specific parts (Checkbox, Label, Toggle) or just inject class names.
• 🚀 Zero Dependencies: Micro-sized footprint with no external runtime dependencies.
• ♿ Accessible: Optimized for use with semantic HTML and standard event handling.

Installation

npm install headless-tree-select
# or
yarn add headless-tree-select

Quick Start

The simplest way to get started is using the default built-in components.

import { TreeSelect } from 'headless-tree-select';
import { useState } from 'react';

const data = [
  {
    id: '1',
    label: 'Engineering',
    children: [
      { id: '1-1', label: 'Frontend' },
      { id: '1-2', label: 'Backend' },
    ],
  },
];

function App() {
  const [checked, setChecked] = useState([]);

  return (
    <TreeSelect 
      data={data} 
      value={checked} 
      onChange={(res) => setChecked(res.checked)} 
    />
  );
}

Customization

1. Granular Component Overrides

You can replace individual parts of the tree row by passing React components.

import { CheckIcon, ChevronRight } from 'lucide-react';

<TreeSelect
  data={data}
  value={checked}
  CheckBox={({ isChecked, isIndeterminate }) => (
    <div className={`custom-cb ${isChecked ? 'checked' : ''}`}>
       {isChecked && <CheckIcon size={12} />}
    </div>
  )}
  ToggleExpand={({ isExpanded, onToggle, hasChildren }) => (
    hasChildren && (
      <button onClick={onToggle} style={{ transform: isExpanded ? 'rotate(90deg)' : 'none' }}>
        <ChevronRight />
      </button>
    )
  )}
  Label={({ node }) => <span className="custom-label">{node.label}</span>}
/>

2. Tailoring with classNames

If you logic the default DOM but want different styles (e.g., using Tailwind CSS):

<TreeSelect
  data={data}
  classNames={{
    container: "space-y-1",
    item: "hover:bg-blue-50 rounded px-2 py-1 flex items-center gap-2",
    checkBox: "rounded border-blue-300 text-blue-600 focus:ring-blue-500",
    label: "text-sm text-gray-700 font-medium",
    toggleExpand: "text-gray-400 hover:text-blue-500",
  }}
/>

API Reference

Props

| Property | Type | Default | Description | | :--- | :--- | :--- | :--- | | data | TreeNode[] | [] | The tree data structure to render. | | value | string[] | [] | Array of currently checked node IDs (controlled). | | onChange | (result: TreeSelectChangeResult) => void | - | Callback triggered when selection or state changes. | | defaultExpandedIds | string[] | [] | IDs of nodes that should be expanded on initial render. | | CheckBox | React.ComponentType<CheckBoxProps> | - | Custom component for the checkbox. | | ToggleExpand | React.ComponentType<ToggleExpandProps> | - | Custom component for the expansion needle/toggle. | | Label | React.ComponentType<LabelProps> | - | Custom component for the node label. | | Toggle | React.ComponentType<ToggleProps> | - | Additional optional toggle component (if needed). | | classNames | TreeSelectClassNames | {} | CSS class name slots for styling. |

Data Structures

TreeNode

interface TreeNode {
  id: string;          // Unique identifier
  label: string;       // Display text
  children?: TreeNode[]; // Child nodes
  disabled?: boolean;  // If true, the node cannot be toggled
}

TreeSelectChangeResult

interface TreeSelectChangeResult {
  checked: string[];     // All fully selected node IDs
  halfChecked: string[]; // All indeterminate node IDs
}

Development

# Clone the repository
git clone https://github.com/imwind/headless-tree-select.git

# Install dependencies
npm install

# Start development build
npm run dev

# Run tests
npm run test

# Build production bundle
npm run build

License

MIT © imwind