React Tree List

A flexible and performant React component library for building trees, lists, and virtualized scrollable views with multi-selection support.

Installation

npm install @dazl/tree-list
# or
yarn add @dazl/tree-list
# or
pnpm add @dazl/tree-list

Features

• 🌲 Tree View: Hierarchical tree component with collapsible nodes
• 📋 List: Simple list component with keyboard navigation and selection
• 🔄 ScrollList: Virtualized list for efficiently rendering large datasets
• ⌨️ Keyboard Navigation: Full keyboard navigation support
• ✅ Multi-selection: Support for range selection and multi-selection with modifier keys
• 🔍 Virtualization: Render only visible items for performance
• 📱 Responsive: Works with both horizontal and vertical layouts

Components

List

A basic list component with selection and keyboard navigation.

import { List } from '@dazl/tree-list';
import type { ListItem } from '@dazl/tree-list';

interface ItemData {
  id: string;
  title: string;
}

const items = [
  { id: '1', title: 'Item 1' },
  { id: '2', title: 'Item 2' },
  { id: '3', title: 'Item 3' },
];

const ItemRenderer = ({ id, data, isFocused, isSelected }: ListItem<ItemData>) => (
  <div 
    data-id={id}
    style={{
      background: isSelected ? 'lightblue' : 'white',
      border: isFocused ? '1px solid blue' : '1px solid transparent',
      padding: '8px',
    }}
  >
    {data.title}
  </div>
);

function MyList() {
  const [selectedIds, setSelectedIds] = useState({ ids: [] });
  const [focusedId, setFocusedId] = useState();
  
  return (
    <List
      items={items}
      getId={(item) => item.id}
      ItemRenderer={ItemRenderer}
      selectedIds={selectedIds}
      setSelectedIds={setSelectedIds}
      focusedId={focusedId}
      setFocusedId={setFocusedId}
    />
  );
}

ScrollList

A virtualized list for efficiently rendering large datasets.

import { ScrollList } from '@dazl/tree-list/scroll-list';

function MyScrollList() {
  const [selectedIds, setSelectedIds] = useState({ ids: [] });
  const [focusedId, setFocusedId] = useState();
  
  return (
    <ScrollList
      items={manyItems}
      getId={(item) => item.id}
      ItemRenderer={ItemRenderer}
      selectedIds={selectedIds}
      setSelectedIds={setSelectedIds}
      focusedId={focusedId}
      setFocusedId={setFocusedId}
      scrollListContainerProps={{ 
        style: { 
          height: '500px',
          overflow: 'auto'
        } 
      }}
      extraRenderSize={1}
      scrollToFocused
    />
  );
}

Tree

A hierarchical tree component with collapsible nodes.

import { Tree } from '@dazl/tree-list/tree';
import type { TreeItemProps } from '@dazl/tree-list';

interface TreeItemData {
  id: string;
  name: string;
  children: TreeItemData[];
}

const TreeItemRenderer = ({ 
  id, 
  data, 
  isSelected, 
  isFocused, 
  isOpen, 
  hasChildren, 
  indent, 
  open, 
  close 
}: TreeItemProps<TreeItemData>) => (
  <div
    data-id={id}
    style={{
      paddingLeft: `${indent * 20}px`,
      background: isSelected ? 'lightblue' : 'white',
      border: isFocused ? '1px solid blue' : '1px solid transparent',
    }}
  >
    {hasChildren && (
      <button onClick={isOpen ? close : open}>
        {isOpen ? '▼' : '►'}
      </button>
    )}
    {data.name}
  </div>
);

function MyTree() {
  const [selectedIds, setSelectedIds] = useState({ ids: [] });
  const [focusedId, setFocusedId] = useState();
  const [openItemIds, setOpenItemIds] = useState(['root']);
  
  return (
    <Tree
      data={treeData}
      getChildren={(item) => item.children}
      getId={(item) => item.id}
      ItemRenderer={TreeItemRenderer}
      selectedIds={selectedIds}
      setSelectedIds={setSelectedIds}
      focusedId={focusedId}
      setFocusedId={setFocusedId}
      openItemIds={openItemIds}
      setOpenItemIds={setOpenItemIds}
    />
  );
}

API Documentation

List Props

| Prop | Type | Description | |------|------|-------------| | items | T[] | Array of items to render | | getId | (item: T) => string | Function to extract unique id from item | | ItemRenderer | React.FC<ListItem<T>> | Component to render each item | | selectedIds | { ids: string[], lastSelectedId?: string } | Currently selected item ids | | setSelectedIds | (selection: ListSelection) => void | Callback to update selection | | focusedId | string \| undefined | Currently focused item id | | setFocusedId | (id?: string) => void | Callback to update focus | | enableKeyboard | boolean | Enable keyboard navigation (default: true) | | enableMultiselect | boolean | Enable multiple selection (default: true) | | style | React.CSSProperties | Custom styles for the list container | | listRef | React.RefObject<HTMLDivElement> | Ref for the list container | | listContainerProps | React.HTMLAttributes<HTMLDivElement> | Additional props for list container |

See the source code for more detailed type definitions and additional components.

License

MIT