Search Functionality

Searching for items is natively supported. It looks through all items that are curretly visible in the tree, similar to how other tree implementations do it such as the tree view in IntelliJ or VsCode. Search is automatically started if the tree is focused and the user starts typing.

This also implements the accessibility feature where entering a single character while focusing the tree should move the focus to the first item that matches the character. See the W3C spec for keyboard bindings for more details.

info

All props that can be provided to the tree environment to control search capabilities are documented in the TreeCapabilities interface.

danger

(TODO) Apparently the search currently does not work properly in the docs pages, where the search input is not properly shown. This is an issue with our documentation tooling, not the framework. Working examples are available in the storybook.

Example

Try focusing the tree (i.e. by clicking on it) and start typing to search.

Live Editor

function App() { return ( <UncontrolledTreeEnvironment dataProvider={new StaticTreeDataProvider(longTree.items, (item, data) => ({ ...item, data }))} getItemTitle={item => item.data} viewState={{ 'tree-1': { expandedItems: ['Fruit', 'Meals'], }, }} > <Tree treeId="tree-1" rootItem="root" treeLabel="Tree Example" /> </UncontrolledTreeEnvironment> ); }

function App() {
  return (
    <UncontrolledTreeEnvironment
      dataProvider={new StaticTreeDataProvider(longTree.items, (item, data) => ({ ...item, data }))}
      getItemTitle={item => item.data}
      viewState={{
        'tree-1': {
          expandedItems: ['Fruit', 'Meals'],
        },
      }}
    >
      <Tree treeId="tree-1" rootItem="root" treeLabel="Tree Example" />
    </UncontrolledTreeEnvironment>
  );
}

Result

Loading...

Configurability

The prop canSearchByStartingTyping manages whether the search can be initiated by just starting to type while focusing the tree. In the following example, the hotkey F1 needs to be pressed to start search.

Live Editor

function App() { return ( <UncontrolledTreeEnvironment dataProvider={new StaticTreeDataProvider(longTree.items, (item, data) => ({ ...item, data }))} getItemTitle={item => item.data} viewState={{ 'tree-2': { expandedItems: ['Fruit', 'Meals'], }, }} canSearchByStartingTyping={false} keyboardBindings={{ startSearch: ['f1'], }} > <Tree treeId="tree-2" rootItem="root" treeLabel="Tree Example" /> </UncontrolledTreeEnvironment> ); }

function App() {
  return (
    <UncontrolledTreeEnvironment
      dataProvider={new StaticTreeDataProvider(longTree.items, (item, data) => ({ ...item, data }))}
      getItemTitle={item => item.data}
      viewState={{
        'tree-2': {
          expandedItems: ['Fruit', 'Meals'],
        },
      }}
      canSearchByStartingTyping={false}
      keyboardBindings={{
        startSearch: ['f1'],
      }}
    >
      <Tree treeId="tree-2" rootItem="root" treeLabel="Tree Example" />
    </UncontrolledTreeEnvironment>
  );
}

Result

Loading...

Search can also be disabled completely by setting the prop canSearch to false.

Live Editor

function App() { return ( <UncontrolledTreeEnvironment dataProvider={new StaticTreeDataProvider(longTree.items, (item, data) => ({ ...item, data }))} getItemTitle={item => item.data} viewState={{ 'tree-3': { expandedItems: ['Fruit', 'Meals'], }, }} canSearch={false} > <Tree treeId="tree-3" rootItem="root" treeLabel="Tree Example" /> </UncontrolledTreeEnvironment> ); }

function App() {
  return (
    <UncontrolledTreeEnvironment
      dataProvider={new StaticTreeDataProvider(longTree.items, (item, data) => ({ ...item, data }))}
      getItemTitle={item => item.data}
      viewState={{
        'tree-3': {
          expandedItems: ['Fruit', 'Meals'],
        },
      }}
      canSearch={false}
    >
      <Tree treeId="tree-3" rootItem="root" treeLabel="Tree Example" />
    </UncontrolledTreeEnvironment>
  );
}

Result

Loading...

Programmatic interaction

This feature can programmatically be controlled by pulling a React Ref either from the tree environment or the tree itself, and acting on the Ref object. Read the documentation on externally interacting with the tree via Refs to find out more.