A fast, efficient tree table component for ReactJS.

Installation

Using npm:

$ npm install --save cp-react-tree-table

Using yarn:

$ yarn add cp-react-tree-table

Usage

import { TreeTable, TreeState } from 'cp-react-tree-table';

const MOCK_DATA = [
  ...
  {
    data: { name: 'Company I', expenses: '105,000', employees: '22', contact: 'Makenzie Higgs' },
    children: [
      { 
        data: { name: 'Department 1', expenses: '75,000', employees: '18', contact: 'Florence Carter' },
      },
      ...
    ]
  },
  ...
];

class Demo extends React.Component {
  constructor(props) {
    super(props);
    
    this.state = {
      treeValue: TreeState.create(MOCK_DATA)
    };
  }

  render() {
    const { treeValue } = this.state;

    return (
      <TreeTable
        value={treeValue}
        onChange={this.handleOnChange}>

        <TreeTable.Column
          renderCell={this.renderNameCell}
          renderHeaderCell={() => <span>Name</span>}/>
        ...
      </TreeTable>
   );
  }

  handleOnChange = (newValue) => {
    this.setState({ treeValue: newValue });
  }

  renderNameCell = (row) => {
    return (
      <span>{row.data.name}</span>
    );
  }

  ...
}

Properties

depth

number

Starts from 0, indicates the depth level of the node represented by this row inside the tree.

index

number

Indicates the position of the row inside the visual representation of the tree.

height

number

The height of the row in pixels.

hasChildren

boolean

Whether the node represented by this row has children.

Properties

isVisible

boolean

Whether the node represented by this row is visible.

isExpanded

boolean

Whether the node represented by this row is expanded, displaying all its children.

top

number

The height of all visible rows displayed above.

Public Properties

data

any

The node data object.

metadata

RowMetadata

Metadata object containing properties of the corresponding node.

$state

RowState

Metadata object describing the row's visual state.

Public Methods

toggleChildren

() => void

Will toggle direct descendants of the node represented by the current row. If the direct descendants don't share the same visibility state, the updated state will be determined by the isVisible property of the first descendant.

NOTE:

This will trigger an onChange event. Changes will be rendered by passing the new state to the value prop of TreeTable.

updateData

(newData: any) => void

Will update the data object.

NOTE:

This will trigger an onChange event. Changes will be rendered by passing the new state to the value prop of TreeTable.

Properties

data

any

The data object.

children

Array<TreeNode>

List of children TreeNode nodes.

height

number

The height value of the row that will represent the node (pixels). Defaults to 26 if no value is provided.

Represents a snapshot of the state of the table. Changes within the table will create new TreeState objects, which will be provided by the onChange event on TreeTable. This follows the controlled component API pattern.

Public Properties

data

Array<RowModel>

The internal representation of the tree.

height

number

The height of the visual representation of the tree, in its current state (pixels).

hasData

boolean

Whether the tree represented by this object contains any nodes.

Public Methods

findRowModel

(node: TreeNode>) => RowModel|undefined

Returns the RowModel object that corresponds to the given node.

Public Static Methods

create

(data: Array<TreeNode>) => Readonly<TreeState>

Returns a new TreeState object based on the provided tree data.

createEmpty

() => Readonly<TreeState>

Returns a new TreeState object with no tree data.

expandAll

(source: Readonly<TreeState>, depthLimit?: number) => Readonly<TreeState>

Returns a new TreeState object with all tree nodes expanded (for depthLimit set to undefined). If depthLimit is provided, expands only nodes with their depth value less than depthLimit.

collapseAll

(source: Readonly<TreeState>) => Readonly<TreeState>

Returns a new TreeState object with all tree nodes collapsed.

expandAncestors

(source: Readonly<TreeState>, model: RowModel) => Readonly<TreeState>

Returns a new TreeState object with all ancestors for the given node expanded.

Props

renderCell

(row: Row) => Node

Table cell renderer.

renderHeaderCell

() => Node

Header cell renderer.

grow

number

flexGrow CSS property

basis

string

flexBasis CSS property

Props

value

Readonly<TreeState>

The TreeState object to be rendered by the TreeTable component.

onChange

(value: Readonly<TreeState>) => void

The onChange event to be called when changes occur. Changes will be rendered by passing the new state to the value prop.

children

Array<React.ReactElement<TreeTable.Column>>

A list of TreeTable.Column components that will be used to render the table.

onScroll

(scrollTop: number) => void

The onScroll event to be called when the table's content is being scrolled.

height

number

The height of the rendered table (pixels).

headerHeight

number

The height of the rendered header row (pixels).

className

string

The custom string that will be appended to the classList of TreeTable's root element.

Public Methods

scrollTo

(posY: number) => void

Scrolls the content of the table to a given position (pixels).

import { TreeTable, TreeState } from 'cp-react-tree-table';

class Demo extends React.Component {

  ...
  render() {
    return (
      <React.Fragment>
        <button onClick={this.handleOnExpandAll}>Expand all</button>
        <button onClick={this.handleOnCollapseAll}>Collapse all</button>

        <TreeTable
          value={this.state.treeValue}
          onChange={(value) => this.setState({treeValue: value})}>
          ...
        </TreeTable>
      </React.Fragment>
    );
  }

  ...
  handleOnExpandAll = () => {
    this.setState((state) => {
      return {
        treeValue: TreeState.expandAll(state.treeValue),
      };
    });
  }
  handleOnCollapseAll = () => {
    this.setState((state) => {
      return {
        treeValue: TreeState.collapseAll(state.treeValue)
      };
    });
  }
}

import { TreeTable, TreeState } from 'cp-react-tree-table';

class Demo extends React.Component {

  ...
  render() {
    return (
      <TreeTable
        value={this.state.treeValue}
        onChange={(value) => this.setState({treeValue: value})}>
        ...
        <TreeTable.Column
          renderCell={this.renderEditableCell}
          renderHeaderCell={() => <span>Contact person</span>}/>
        ...
      </TreeTable>
    );
  }

  ...
  renderEditableCell = (row) => {
    return (
      <input type="text" value={row.data.contact}
        onChange={(event) => {
          row.updateData({
            ...row.data,
            contact: event.target.value,
          });
        }}/>
    );
  }
}

import { TreeTable, TreeState } from 'cp-react-tree-table';

class Demo extends React.Component {
  ...
  render() {
    return (
      <React.Fragment>
        <button onClick={this.handleScrollToGroupBeta}>Scroll to "Group Beta"</button>

        <TreeTable
          value={this.state.treeValue}
          onChange={(value) => this.setState({treeValue: value})}

          ref={this.treeTableRef}>
          ...
        </TreeTable>
      </React.Fragment>
    );
  }

  ...
  handleScrollToGroupBeta = () => {
    console.log('Scroll to "Group Beta"');
    const { treeValue } = this.state;

    // The node to which the table's viewport will scroll to
    const node = MOCK_DATA[8].children[0].children[1];
    const rowModel = treeValue.findRowModel(node);
    if (rowModel != null) {
      this.setState({
        treeValue: TreeState.expandAncestors(treeValue, rowModel),
      }, () => {
        if (this.treeTableRef.current != null) {
          this.treeTableRef.current.scrollTo(rowModel.$state.top);
        }
      });
    }
  }
}

import { TreeTable, TreeState } from 'cp-react-tree-table';

class Demo extends React.Component {
  treeTableRef = React.createRef();
  ...
  render() {
    return (
      <React.Fragment>
        <button onClick={this.handleScrollTo}>Scroll to 100px</button>

        <TreeTable
          value={this.state.treeValue}
          onChange={(value) => this.setState({treeValue: value})}

          ref={this.treeTableRef}>
          ...
        </TreeTable>
      </React.Fragment>
    );
  }

  ...
  handleScrollTo = () => {
    if (this.treeTableRef.current != null) {
      this.treeTableRef.current.scrollTo(100);
    }
  }
}

In v1.0, library bindings are exported as named exports:

import { TreeTable, TreeState } from 'cp-react-tree-table';

Inv1.0, findRowModel(node), expandAncestors(treeState, rowModel) and scrollTo(posY) can be used to replace the functionality offered by scrollIntoView(node, expandAncestors) from v0.x.

Example — scroll to a specific node