npm version npm downloads bundle size TypeScript License: MIT

A React tree component for hand-crafted hierarchical interfaces. Unlike data-driven tree libraries, handtree lets you compose tree structures manually with full control over styling, behavior, and layout.

📖 Live Examples & Documentation →

Most tree components are data-driven - they work well when you can normalize your data into a homogeneous structure like {id, children}. But many real-world scenarios resist this normalization:

// Hard to normalize - different node types, mixed content
const jsonSchema = {
 User: { type: 'object', required: true, properties: {
 id: { type: 'string', validation: /\d+/ },
 profile: { type: 'object', properties: {
 name: { type: 'string', maxLength: 50 },
 settings: { type: 'array', items: 'string' }
 }}
 }}
}

handtree is perfect when you need to:

1. Handle complex nested data structures that don't fit a uniform schema
2. Different node content and behaviors for different node types (objects vs arrays vs primitives, each with unique styling and interactions)

Instead of forcing your data into a generic tree format, handtree lets you craft each node type exactly as it should appear and behave.

Real-world usage: OpenAPI schema editor where each field type (object, array, string, number) has unique rendering, metadata, and interactions. Note the rich details below each field (descriptions, examples, constraints) - this level of content is difficult and often not worth normalizing into a generic tree structure.

handtree powers the hierarchical interfaces in reapi.com - an OpenAPI schema editor and no-code testing platform. It handles complex nested schemas with hundreds of nodes while maintaining smooth performance and user experience.

npm install handtree
# or
pnpm add handtree
# or 
yarn add handtree

The core pattern is using TreeNode as a visual renderer inside your own data-type-oriented components. You don't use TreeNode directly - instead, you create components that understand your specific data structure and use TreeNode to render the tree visualization.

// Your data-oriented component
function JsonSchemaNode({ schema, level }) {
 return (
 <TreeNode
 level={level}
 expandable={schema.type === 'object'}
 title={<SchemaTitle data={schema} />}
 details={<SchemaDetails data={schema} />}
 >
 {schema.properties?.map(prop => 
 <JsonSchemaNode key={prop.name} schema={prop} level={level + 1} />
 )}
 </TreeNode>
 )
}
// Your custom title component
function SchemaTitle({ data }) {
 return (
 <span className="flex items-center gap-2">
 <span className="text-blue-600 font-bold">{data.name}</span>
 <span className="text-gray-500">:</span>
 <span style={{ color: getTypeColor(data.type) }}>{data.type}</span>
 {data.required && <span className="text-xs bg-red-100 text-red-800 px-1 rounded">required</span>}
 </span>
 )
}
// Your custom details component 
function SchemaDetails({ data }) {
 return data.description ? (
 <div className="text-xs text-gray-600 italic py-1">
 {data.description}
 {data.validation && <code className="ml-2 bg-gray-100 px-1">{data.validation.toString()}</code>}
 </div>
 ) : null
}
// Usage
<TreeContext.Provider value={{ indent: 24, ancestorLastTrail: [], classNames: {} }}>
 <JsonSchemaNode schema={mySchema} level={0} />
</TreeContext.Provider>

This way, JsonSchemaNode handles the business logic (what's expandable, how to render titles), while TreeNode handles the tree visualization (lines, indentation, expand/collapse UI).

Unlike traditional tree components that only show a title per node, handtree supports rich details content below each title. This is perfect for showing:

• Documentation (API descriptions, schema details)
• Metadata (file sizes, timestamps, validation rules)
• Status indicators (health checks, build results)
• Secondary actions (buttons, links, badges)

The details section maintains proper tree indentation and connecting lines, creating a clean hierarchical layout even with complex content.

Provides configuration for the entire tree.

interface ITreeContext {
 indent: number // Indentation per level (px)
 ancestorLastTrail: boolean[] // Internal: tracks line drawing
 classNames: Record<string, string> // Custom CSS classes
}

The visual renderer component. This handles tree UI concerns (indentation, connecting lines, expand/collapse icons) while you handle the data concerns in your wrapper component.

interface TreeNodeProps {
 level: number // Nesting level (0 = root)
 lastNode?: boolean // Is this the last sibling?
 title: React.ReactNode // Node content (your custom JSX)
 details?: React.ReactNode // Additional details below title
 children?: React.ReactNode // Child nodes (usually more of your wrapper components)
 expandable?: boolean // Can this node be expanded?
 expanded?: boolean // Is this node expanded?
 onToggleExpanded?: () => void // Expand/collapse handler
}

Key responsibilities:

• Visual structure: Draws connecting lines, handles indentation
• Expand/collapse UI: Shows icons and handles click interactions
• Layout: Positions title, details, and children properly

Your wrapper component handles:

• Data interpretation: What should be expandable? What's the title?
• Business logic: State management, event handling
• Content rendering: Custom styling, icons, badges, etc.

Explore interactive examples and see handtree in action:

📖 Live Examples & Documentation →

• Basic Tree View - Simple hierarchical structure showing the core TreeNode API
• Interactive JSON Schema Explorer - Complex nested data with custom styling, expand/collapse state management, and rich details content. Perfect example of handling heterogeneous data structures that resist normalization.
• Minimal Example - Lightweight implementation showing the essential patterns

handtree uses prefixed CSS classes that you can easily override:

/* Customize tree lines color */
.handtree-root {
 --outline-color: #0066cc;
}
/* Style the expand/collapse icons */
.handtree-head {
 color: #666;
}
.handtree-head:hover {
 color: #0066cc;
}
/* Customize spacing */
.handtree-root {
 --indent-width: 32px;
 --head-width: 30px;
}

Available CSS classes:

• .handtree-root - Root container
• .handtree-node - Individual node wrapper
• .handtree-head - Expand/collapse area
• .handtree-title - Title content area
• .handtree-details - Details content area
• .handtree-content - Main content wrapper
• .handtree-indent - Indentation guides

CSS Variables:

• --outline-color - Tree connecting lines color
• --indent-width - Indentation per level
• --head-width - Width of expand/collapse area

# Install dependencies 
pnpm install
# Start development with hot reload
pnpm dev
# View component demos
pnpm ladle:serve
# Build for production
pnpm build

We welcome contributions! Please see our contributing guidelines for details.

MIT © [Your Name]