Headless Tree Documentation

Headless Tree is a library for integrating complex tree components into React applications. It provides the logic for advanced tree features while remaining unopinionated about styling and rendering.

Key characteristics:

• Flat List Interface: Instead of a nested structure, the library provides a flat list of tree nodes. This makes it easy to render and compatible with virtualization libraries (like react-window or react-virtuoso) to support very large trees (100k+ items).
• Accessibility: Even though the data structure is flat, the library automatically provides the necessary ARIA tags to emulate a nested tree structure for screen readers.
• Headless: You are responsible for the DOM and CSS; the library provides the state, keyboard interactions, and accessibility attributes.
• Successor to react-complex-tree: It is the official successor to the react-complex-tree project.

Headless Tree uses a plugin-based architecture where individual features (like drag-and-drop or hotkeys) are separate objects. This allows for better tree-shaking and customizability.

Important Rules:

• Manual Import Required: You must explicitly import features from @headless-tree/core and add them to the features array in your TreeConfig.
• Runtime Availability: If you attempt to use a method or config option provided by a feature but haven't included that feature in your features array, the method will not work at runtime (even if TypeScript doesn't complain).
• Built-in Features: "Tree Core" and "Main Feature" are always included and do not need to be manually added.

Example of adding features:

import { dragAndDropFeature, hotkeysCoreFeature, syncDataLoaderFeature } from "@headless-tree/core";
import { useTree } from "@headless-tree/react";

useTree({
    features: [
        syncDataLoaderFeature,
        dragAndDropFeature,
        hotkeysCoreFeature,
    ]
});

import { dragAndDropFeature, hotkeysCoreFeature, syncDataLoaderFeature } from "@headless-tree/core";
import { useTree } from "@headless-tree/react";

useTree({
    // ... other options
    features: [
        syncDataLoaderFeature,
        dragAndDropFeature,
        hotkeysCoreFeature,
    ]
})

Headless Tree is built using a modular feature system. Instead of a monolithic core, functionality is provided by individual feature objects that can be optionally included in the tree configuration. This allows for reduced bundle sizes by only including necessary features and enables deep customization.

Each feature is an object imported from @headless-tree/core that interacts with the tree through several interfaces:

• State: The feature's substate is merged into the global TreeState. You can manage this state using the provided state setters or your own setState function.
• Config: Feature-specific configuration options are merged into the global TreeConfig.
• Tree Instance: Methods provided by the feature that are accessible via the TreeInstance (e.g., tree.someFeatureMethod()).
• Item Instance: Methods provided by the feature that are accessible via the ItemInstance (e.g., tree.getItemInstance(id).someFeatureMethod()).
• Hotkeys: If the hotkeysCoreFeature is included, the feature's defined hotkeys will be active and can be customized via the hotkeys config object.

const tree = useTree<string>({
  // ...remaining tree config
  state: { selectedItems: ["item-1", "item-2"] },
  setSelectedItems: myCustomSetSelectedItems,

  hotkeys: {
    // Override hotkey definitions for this feature
    selectAll: {
      hotkey: "ctrl+q",
    },
  },
  features: [
    syncDataLoaderFeature,
    selectionFeature,
    hotkeysCoreFeature,
  ],
});

// Interact with tree instance methods
tree.setSelectedItems(["item-3", "item-4"]);

// Interact with item instance methods
tree.getItemInstance("item-1").select();