@clevertask/react-sortable-tree v0.0.7

@clevertask/react-sortable-tree

A customizable React component for rendering and managing tree structures with drag-and-drop functionality. Built on top of the dnd-kit sortable tree example.

This library is currently focused on custom item rendering and type-safe tree structures. A more detailed API and feature set will be released in a future major version with support for virtualization and multi-selection.

Table of Contents

• Installation
• Usage
• Props
• Types
• Helper Functions
• Roadmap
• License

Installation

npm install @clevertask/react-sortable-tree

Usage

1. Define your custom tree item type if needed

type CustomTreeItem = TreeItem<{
  metadata?: Record<string, any>;
  icon?: string;
}>;

Otherwise, the component will use the default tree item type.

2. Create your custom item component

This is the basic structure you can start with:

import {
  RenderItemProps,
  TreeItemStructure,
  createSortableTreeGlobalStyles,
  RenderItemProps,
} from '@clevertask/react-sortable-tree';

export const TreeItem = ({ treeItem, collapsed, onCollapse, ...rest }: RenderItemProps) => {
  <TreeItemStructure {...rest}>
    <button {...dragListeners}>Drag me</button>
    {onCollapse && <button onClick={onCollapse}>{collapsed ? 'Expand' : 'Collapse'}</button>}

    <h5>{treeItem.label}</h5>

    <button onClick={() => openItemInfoModal(treeItem.id)}>Show treeItem info</button>
  </TreeItemStructure>;
};

This is a real-world example using Radix:

import {
  RenderItemProps,
  TreeItemStructure,
  createSortableTreeGlobalStyles,
  TreeItem as TTreeItem,
} from '@clevertask/react-sortable-tree';
import {
  DragHandleDots2Icon,
  ChevronRightIcon,
  ChevronDownIcon,
  TrashIcon,
  PlusIcon,
} from '@radix-ui/react-icons';
import { Flex, Button, Text, Box } from '@radix-ui/themes';
import { CustomTreeItem } from '.';

export const TreeItem = ({
  treeItem,
  dragListeners,
  onCollapse,
  collapsed,
  onClickAddNestedItemButton,
  onClickItemRemoveButton,
  onItemClick,
  ...rest
}: RenderItemProps<CustomTreeItem> & {
  onClickAddNestedItemButton: (id: string) => void;
  onClickItemRemoveButton: (id: string) => void;
  onItemClick: (id: string) => void;
}) => {
  const useSortableTreeGlobalStyles = createSortableTreeGlobalStyles({
    indicatorColor: 'var(--orange-7)',
    indicatorBorderColor: 'var(--orange-7)',
  });

  useSortableTreeGlobalStyles();

  return (
    <TreeItemStructure
      {...rest}
      asDropZone={Box}
      asDraggableItem={Box}
      draggableItemStyle={{
        display: 'flex',
        justifyContent: 'space-between',
        padding: '1rem',
        border: '1px solid var(--gray-3)',
        background: 'var(--color-background)',
      }}
    >
      <Flex align="center" gap="5" direction="row">
        <Button color="gray" variant="ghost" {...dragListeners}>
          <DragHandleDots2Icon />
        </Button>

        {onCollapse && (
          <Button color="gray" variant="ghost" onClick={onCollapse}>
            {collapsed ?
              <ChevronRightIcon />
            : <ChevronDownIcon />}
          </Button>
        )}

        <Text style={{ cursor: 'pointer' }} onClick={() => onItemClick(treeItem.id)}>
          {treeItem.label} {treeItem.metadata.foo}
        </Text>
      </Flex>

      <Flex align="center" gap="3" direction="row">
        <Button variant="ghost" color="red" onClick={() => onClickItemRemoveButton(treeItem.id)}>
          <TrashIcon />
        </Button>
        <Button
          variant="ghost"
          color="gray"
          onClick={() => onClickAddNestedItemButton(treeItem.id)}
        >
          <PlusIcon />
        </Button>
      </Flex>
    </TreeItemStructure>
  );
};

The <TreeItemStructure/> appends the dataSlots (for CSS styles), dropzone, and drag item container listeners and refs so you don't have to do it from scratch, but it's possible making your custom tree items without that component.

3. Use the SortableTree with your custom item

import React, { useState } from 'react';
import { TreeItems, SortableTree } from '@clevertask/react-sortable-tree';
type CustomTreeItem = TreeItem<{ metadata?: Record<string, string> }>;

const [items, setItems] = useState<TreeItems<CustomTreeItem>>([
  { id: '1', label: 'Item 1', children: [] },
  {
    id: '2',
    label: 'Item 2',
    children: [{ id: '3', label: 'Item 2.1', children: [] }],
    metadata: { foo: 'foo' },
  },
]);

<SortableTree<CustomTreeItem>
  isCollapsible
  showDropIndicator
  items={items}
  setItems={setItems}
  renderItem={(props: RenderItemProps<CustomTreeItem>) => (
    <TreeItem
      {...props}
      onClickAddNestedItemButton={onClickAddNestedItemButton}
      onClickItemRemoveButton={onClickItemRemoveButton}
      onItemClick={onItemClick}
    />
  )}
/>;

Props

Types

TreeItem

type TreeItem<ExtraProps = unknown> = {
  id: UniqueIdentifier;
  label: string;
  children: TreeItem<ExtraProps>[];
  collapsed?: boolean;
  canFetchChildren?: boolean;
  disableDragging?: boolean;
} & ExtraProps;

TreeItems

type TreeItems<T = TreeItem> = T[];

TreeStructureProps

export interface TreeItemStructureProps {
  dropZoneRef: (element: HTMLElement | null) => void;
  draggableItemRef: React.Ref<any>;
  dropZoneStyle?: React.CSSProperties;
  draggableItemStyle?: React.CSSProperties;
  classNames?: {
    dropZone?: string;
    draggableItem?: string;
  };
  asDropZone?: React.ElementType;
  asDraggableItem?: React.ElementType;
  draggableItemProps?: Record<string, any>;
  children?: React.ReactNode;
  dataSlots: {
    dropZone: Record<string, string | boolean | undefined>;
    draggableItem: Record<string, string>;
  };
}

RenderItemProps

export interface RenderItemProps<T extends TTreeItem = TTreeItem>
  extends Pick<
      TreeItemStructureProps,
      'classNames' | 'dropZoneStyle' | 'dropZoneRef' | 'draggableItemRef'
    >,
    Pick<
      Props,
      | 'onCollapse'
      | 'childCount'
      | 'clone'
      | 'ghost'
      | 'indicator'
      | 'disableSelection'
      | 'disableInteraction'
      | 'collapsed'
    > {
  dragListeners?: any;
  treeItem: T;
  dataSlots: {
    dropZone: Record<string, string | boolean | undefined>;
    draggableItem: Record<string, string>;
  };
}

Helper Functions

getItemById

function getItemById<T extends TreeItem>(items: TreeItems<T>, id: UniqueIdentifier): T | undefined;

removeItemById

function removeItemById<T extends TreeItem>(
  items: TreeItems<T>,
  id: UniqueIdentifier,
): TreeItems<T>;

setTreeItemProperties

function setTreeItemProperties<T extends TreeItem>(
  items: TreeItems<T>,
  id: UniqueIdentifier,
  setter: (value: T) => Partial<T>,
): TreeItems<T>;

Roadmap

• ✅ Custom item rendering (done!)
• 🔜 Virtualization for large trees
• 🔜 Multi-selection support
• 🔜 Drag multiple items
• 🔜 Keyboard navigation
• 🔜 API usage example
• 🔜 E2E tests

License

MIT