TreeSelect

Select with hierarchical tree data

Usage

TreeSelect allows picking one or more values from hierarchical data:

import { TreeSelect } from '@mantine/core';
import { data } from './data';

function Demo() {
  return (
    <TreeSelect
      label="Your favorite item"
      placeholder="Pick value"
      data={data}
    />
  );
}

TreeSelect with uncontrolled forms

Set name to submit node values rather than labels. In multiple and checkbox modes, values share one field; hiddenInputValuesDivider sets the separator:

import { TreeSelect } from '@mantine/core';

function Demo() {
  return (
    <form
      onSubmit={(event) => {
        event.preventDefault();
        const data = new FormData(event.currentTarget);
        console.log(data.get('languages'));
      }}
    >
      <TreeSelect
        name="languages"
        label="Languages"
        mode="multiple"
        data={[
          { value: 'js', label: 'JavaScript' },
          { value: 'ts', label: 'TypeScript' },
        ]}
        defaultValue={['js', 'ts']}
      />
      <button type="submit">Submit</button>
    </form>
  );
}

Virtualized dropdown

Use virtualizer to render only the visible tree rows. Expand or collapse a category to change which products appear:

import { TreeSelect } from '@mantine/core';
import { catalog } from './data';
import { VirtualList } from './VirtualList';

function Demo() {
  return (
    <TreeSelect
      label="Browse the catalog"
      placeholder="Choose a product"
      data={catalog}
      defaultExpandAll
      virtualizer={VirtualList}
    />
  );
}

Data prop

Data passed to the data prop must follow the same rules as the Tree component:

  • Data must be an array of TreeNodeData objects
  • Each node must have value and label keys, value must be unique
  • Each node can have a children key with an array of child nodes
import { TreeNodeData } from '@mantine/core';

const data: TreeNodeData[] = [
  {
    value: 'fruits',
    label: 'Fruits',
    children: [
      { value: 'apple', label: 'Apple' },
      { value: 'banana', label: 'Banana' },
    ],
  },
  { value: 'milk', label: 'Milk' },
];

Selection modes

Use the mode prop to change the selection mode:

  • single (default) – single value selection, renders as an input
  • multiple – multiple value selection, renders as pills
  • checkbox – checkbox selection with parent-child cascade, renders as pills

Multiple mode

import { TreeSelect } from '@mantine/core';
import { data } from './data';

function Demo() {
  return (
    <TreeSelect
      label="Your favorite items"
      placeholder="Pick values"
      data={data}
      mode="multiple"
      defaultExpandAll
    />
  );
}

Checkbox mode

In checkbox mode, checking or unchecking a parent node does the same for all its children. If only some children are checked, the parent is displayed in indeterminate state:

import { TreeSelect } from '@mantine/core';
import { data } from './data';

function Demo() {
  return (
    <TreeSelect
      label="Select categories"
      placeholder="Pick values"
      data={data}
      mode="checkbox"
      defaultExpandAll
    />
  );
}

Controlled

import { useState } from 'react';
import { TreeSelect } from '@mantine/core';

// Single mode
function SingleDemo() {
  const [value, setValue] = useState<string | null>(null);
  return <TreeSelect data={[]} value={value} onChange={setValue} />;
}

// Multiple or checkbox mode
function MultipleDemo() {
  const [value, setValue] = useState<string[]>([]);
  return <TreeSelect data={[]} mode="multiple" value={value} onChange={setValue} />;
}

Searchable

Set searchable prop to allow filtering options by user input. Matching nodes are displayed together with their ancestors:

import { TreeSelect } from '@mantine/core';
import { data } from './data';

function Demo() {
  return (
    <TreeSelect
      label="Your favorite item"
      placeholder="Pick value"
      data={data}
      searchable
    />
  );
}

Nothing found

Set nothingFoundMessage prop to display a message when no options match the search query or there is no data:

import { TreeSelect } from '@mantine/core';
import { data } from './data';

function Demo() {
  return (
    <TreeSelect
      label="Your favorite item"
      placeholder="Pick value"
      data={data}
      searchable
      nothingFoundMessage="Nothing found..."
    />
  );
}

Clearable

Set the clearable prop to display the clear button in the right section:

import { TreeSelect } from '@mantine/core';
import { data } from './data';

function Demo() {
  return (
    <TreeSelect
      label="Your favorite item"
      placeholder="Pick value"
      data={data}
      defaultValue="iphone"
      defaultExpandedValues={['electronics', 'phones']}
      clearable
    />
  );
}

Expand on click

Set expandOnClick prop to expand and collapse a parent node when it is clicked, not only with the chevron. In checkbox mode, the click also toggles the checked state:

import { TreeSelect } from '@mantine/core';
import { data } from './data';

function Demo() {
  return (
    <TreeSelect
      label="Your favorite item"
      placeholder="Pick value"
      data={data}
      expandOnClick
    />
  );
}

Connecting lines

TreeSelect renders connecting lines between parent and child nodes by default. Set withLines={false} to disable them:

import { TreeSelect } from '@mantine/core';
import { data } from './data';

function Demo() {
  return (
    <TreeSelect
      label="Without connecting lines"
      placeholder="Pick value"
      data={data}
      defaultExpandAll
      withLines={false}
    />
  );
}

Check strictly

Set checkStrictly to disable parent-child cascade in checkbox mode, each node is checked independently:

import { TreeSelect } from '@mantine/core';
import { data } from './data';

function Demo() {
  return (
    <TreeSelect
      label="Select items"
      placeholder="Pick values"
      data={data}
      mode="checkbox"
      checkStrictly
      defaultExpandAll
    />
  );
}

Checked strategy

checkedStrategy prop controls which checked nodes appear in the value and pills in checkbox mode:

  • child (default) – only leaf nodes appear in the value
  • all – all checked nodes (parents and children) appear in the value
  • parent – only the topmost fully-checked parents appear in the value
import { useState } from 'react';
import { Stack, TreeSelect } from '@mantine/core';
import { data } from './data';

function Demo() {
  const [childValue, setChildValue] = useState<string[]>([]);
  const [allValue, setAllValue] = useState<string[]>([]);
  const [parentValue, setParentValue] = useState<string[]>([]);

  return (
    <Stack>
      <TreeSelect
        label="checkedStrategy: child (default)"
        placeholder="Pick values"
        data={data}
        mode="checkbox"
        checkedStrategy="child"
        defaultExpandAll
        value={childValue}
        onChange={setChildValue}
      />
      <TreeSelect
        label="checkedStrategy: all"
        placeholder="Pick values"
        data={data}
        mode="checkbox"
        checkedStrategy="all"
        defaultExpandAll
        value={allValue}
        onChange={setAllValue}
      />
      <TreeSelect
        label="checkedStrategy: parent"
        placeholder="Pick values"
        data={data}
        mode="checkbox"
        checkedStrategy="parent"
        defaultExpandAll
        value={parentValue}
        onChange={setParentValue}
      />
    </Stack>
  );
}

Max values

Set maxValues prop to limit the number of selected values in multiple and checkbox modes:

import { TreeSelect } from '@mantine/core';
import { data } from './data';

function Demo() {
  return (
    <TreeSelect
      label="Pick up to 3 items"
      placeholder="Pick values"
      data={data}
      mode="multiple"
      maxValues={3}
      defaultExpandAll
    />
  );
}

renderNode

Use renderNode callback to customize node rendering in the dropdown:

import { FileTextIcon, FolderOpenIcon, FolderSimpleIcon } from '@phosphor-icons/react';
import { Group, Text, TreeSelect, TreeSelectProps } from '@mantine/core';
import { data } from './data';

const renderTreeNode: TreeSelectProps['renderNode'] = ({ node, hasChildren, expanded }) => (
  <Group gap="xs">
    {hasChildren ? (
      expanded ? (
        <FolderOpenIcon color="var(--mantine-color-yellow-7)" size={16} />
      ) : (
        <FolderSimpleIcon color="var(--mantine-color-yellow-7)" size={16} />
      )
    ) : (
      <FileTextIcon size={16} />
    )}
    <Text size="sm">{node.label}</Text>
  </Group>
);

function Demo() {
  return (
    <TreeSelect
      label="Your favorite item"
      placeholder="Pick value"
      data={data}
      renderNode={renderTreeNode}
      defaultExpandAll
    />
  );
}

The payload includes an expand function that toggles the node. Use it to build a custom expand control, set expandOnClick={false} to expand nodes only with your control:

import { CaretRightIcon } from '@phosphor-icons/react';
import { Group, TreeSelect, TreeSelectProps } from '@mantine/core';
import { data } from './data';

const renderTreeNode: TreeSelectProps['renderNode'] = ({ node, hasChildren, expanded, expand }) => (
  <Group gap="xs" wrap="nowrap">
    {hasChildren ? (
      <CaretRightIcon
        size={14}
        onClick={expand}
        style={{
          cursor: 'pointer',
          transform: expanded ? 'rotate(90deg)' : undefined,
          transition: 'transform 150ms ease',
        }}
      />
    ) : (
      <span style={{ display: 'inline-block', width: 14 }} />
    )}
    <span>{node.label}</span>
  </Group>
);

function Demo() {
  return (
    <TreeSelect
      label="Your favorite item"
      placeholder="Pick value"
      data={data}
      renderNode={renderTreeNode}
      expandOnClick={false}
    />
  );
}

renderPill

Use renderPill callback to customize pills of selected values in multiple and checkbox modes. Call onRemove from your pill to remove the value. The overflow pill is customized with maxDisplayedValuesContent instead:

Phones
Headphones
import { FileTextIcon, FolderSimpleIcon } from '@phosphor-icons/react';
import { Group, Pill, TreeSelect, TreeSelectProps } from '@mantine/core';
import { data } from './data';

const renderTreePill: TreeSelectProps['renderPill'] = ({ node, onRemove, disabled, readOnly }) => (
  <Pill withRemoveButton={!readOnly} onRemove={onRemove} disabled={disabled}>
    <Group gap={4} wrap="nowrap">
      {node.children || node.hasChildren ? (
        <FolderSimpleIcon size={12} />
      ) : (
        <FileTextIcon size={12} />
      )}
      {node.label}
    </Group>
  </Pill>
);

function Demo() {
  return (
    <TreeSelect
      mode="checkbox"
      checkedStrategy="parent"
      label="Categories"
      placeholder="Pick categories"
      data={data}
      defaultValue={['phones', 'headphones']}
      defaultExpandAll
      renderPill={renderTreePill}
    />
  );
}

Scrollable dropdown

The options list is wrapped with ScrollArea.Autosize, set maxDropdownHeight prop to change the dropdown max-height:

import { TreeSelect } from '@mantine/core';
import { data } from './data';

function Demo() {
  return (
    <TreeSelect
      label="Your favorite item"
      placeholder="Pick value"
      data={data}
      defaultExpandAll
      maxDropdownHeight={200}
    />
  );
}

Combobox props

You can override Combobox props with comboboxProps. This is useful when you need to change some of the props that are not exposed by TreeSelect, for example withinPortal:

import { TreeSelect } from '@mantine/core';

function Demo() {
  return <TreeSelect comboboxProps={{ withinPortal: false }} data={[]} />;
}

Change dropdown z-index

import { TreeSelect } from '@mantine/core';

function Demo() {
  return <TreeSelect comboboxProps={{ zIndex: 1000 }} data={[]} />;
}

Control dropdown opened state

Use dropdownOpened prop to control the dropdown opened state, onDropdownOpen and onDropdownClose to listen to its changes:

import { TreeSelect, Button } from '@mantine/core';
import { useDisclosure } from '@mantine/hooks';
import { data } from './data';

function Demo() {
  const [dropdownOpened, { toggle }] = useDisclosure();
  return (
    <>
      <Button onClick={toggle} mb="md">
        Toggle dropdown
      </Button>

      <TreeSelect
        label="Your favorite item"
        placeholder="Pick value"
        data={data}
        dropdownOpened={dropdownOpened}
      />
    </>
  );
}

Dropdown position

By default, the dropdown is displayed below the input if there is enough space, otherwise above it. Set position and middlewares props to change this behavior, they are passed down to the underlying Popover. Example of a dropdown that is always displayed above the input:

import { TreeSelect } from '@mantine/core';
import { data } from './data';

function Demo() {
  return (
    <TreeSelect
      label="Your favorite item"
      placeholder="Pick value"
      data={data}
      comboboxProps={{ position: 'top', middlewares: { flip: false, shift: false } }}
    />
  );
}

Dropdown width

By default, the dropdown width is equal to the input width. Set width in comboboxProps to change it:

import { TreeSelect } from '@mantine/core';
import { data } from './data';

function Demo() {
  return (
    <TreeSelect
      label="Your favorite item"
      placeholder="Pick value"
      data={data}
      comboboxProps={{ width: 200, position: 'bottom-start' }}
    />
  );
}

Dropdown offset

Set offset in comboboxProps to change the dropdown offset:

import { TreeSelect } from '@mantine/core';
import { data } from './data';
import classes from './Demo.module.css';

function Demo() {
  return (
    <TreeSelect
      label="Your favorite item"
      placeholder="Pick value"
      data={data}
      classNames={classes}
      comboboxProps={{ position: 'bottom', middlewares: { flip: false, shift: false }, offset: 0 }}
    />
  );
}

Dropdown animation

By default, dropdown animations are disabled. Set transitionProps to enable them, they are passed down to the underlying Transition component:

import { TreeSelect } from '@mantine/core';
import { data } from './data';

function Demo() {
  return (
    <TreeSelect
      label="Your favorite item"
      placeholder="Pick value"
      data={data}
      comboboxProps={{ transitionProps: { transition: 'pop', duration: 200 } }}
    />
  );
}

Dropdown padding

import { TreeSelect } from '@mantine/core';
import { data } from './data';

function Demo() {
  return (
    <>
      <TreeSelect
        label="Zero padding"
        placeholder="Pick value"
        data={data}
        comboboxProps={{ dropdownPadding: 0 }}
      />
      <TreeSelect
        mt="md"
        label="10px padding"
        placeholder="Pick value"
        data={data}
        comboboxProps={{ dropdownPadding: 10 }}
      />
    </>
  );
}

Dropdown shadow

import { TreeSelect } from '@mantine/core';
import { data } from './data';

function Demo() {
  return (
    <TreeSelect
      label="Your favorite item"
      placeholder="Pick value"
      data={data}
      comboboxProps={{ shadow: 'md' }}
    />
  );
}

Keyboard navigation

TreeSelect supports the following keyboard interactions when the dropdown is open:

  • ArrowRight – expand the highlighted parent node
  • ArrowLeft – collapse the highlighted parent node, or move to its parent
  • ArrowUp / ArrowDown – move between options
  • Enter – select the highlighted option

Expand state

Use defaultExpandedValues, defaultExpandAll or expandedValues with onExpandedChange to manage expanded nodes:

import { TreeSelect } from '@mantine/core';

// Expand specific nodes by default
<TreeSelect data={data} defaultExpandedValues={['fruits', 'vegetables']} />

// Expand all nodes by default
<TreeSelect data={data} defaultExpandAll />

// Controlled expanded state
<TreeSelect
  data={data}
  expandedValues={expandedValues}
  onExpandedChange={setExpandedValues}
/>

Left and right sections

TreeSelect supports leftSection and rightSection props. These sections are rendered with absolute positioning inside the input wrapper. You can use them to display icons, input controls, or any other elements.

You can use the following props to control sections styles and content:

  • rightSection / leftSection – React node to render on the corresponding side of input
  • rightSectionWidth/leftSectionWidth – controls the width of the right section and padding on the corresponding side of the input. By default, it is controlled by the component size prop.
  • rightSectionPointerEvents/leftSectionPointerEvents – controls the pointer-events property of the section. If you want to render a non-interactive element, set it to none to pass clicks through to the input.
import { TreeSelect } from '@mantine/core';
import { SquaresFourIcon } from '@phosphor-icons/react';
import { data } from './data';

function Demo() {
  const icon = <SquaresFourIcon size={16} />;
  return (
    <>
      <TreeSelect
        data={data}
        leftSectionPointerEvents="none"
        leftSection={icon}
        label="Your favorite item"
        placeholder="Your favorite item"
      />
      <TreeSelect
        mt="md"
        data={data}
        rightSectionPointerEvents="none"
        rightSection={icon}
        label="Your favorite item"
        placeholder="Your favorite item"
      />
    </>
  );
}

Input props

TreeSelect component supports Input and Input.Wrapper component features and all input element props. The TreeSelect documentation does not include all features supported by the component – see the Input documentation to learn about all available features.

Input description

Variant
Size
Radius
import { TreeSelect } from '@mantine/core';
import { data } from './data';

function Demo() {
  return (
    <TreeSelect
      label="Input label"
      description="Input description"
      placeholder="Pick value"
      data={data}
    />
  );
}

Read only

Set readOnly to make the input read only, the dropdown is not displayed and onChange is not called:

import { TreeSelect } from '@mantine/core';
import { data } from './data';

function Demo() {
  return (
    <TreeSelect
      label="Your favorite item"
      placeholder="Pick value"
      data={data}
      defaultValue="iphone"
      readOnly
    />
  );
}

Disabled

Set disabled to disable the input:

import { TreeSelect } from '@mantine/core';
import { data } from './data';

function Demo() {
  return (
    <TreeSelect
      label="Your favorite item"
      placeholder="Pick value"
      data={data}
      disabled
    />
  );
}

Error state

Invalid value

import { TreeSelect } from '@mantine/core';
import { data } from './data';

function Demo() {
  return (
    <>
      <TreeSelect
        label="Boolean error"
        placeholder="Boolean error"
        error
        data={data}
      />
      <TreeSelect
        mt="md"
        label="With error message"
        placeholder="With error message"
        error="Invalid value"
        data={data}
      />
    </>
  );
}

Success state

Looks good!

import { TreeSelect } from '@mantine/core';
import { data } from './data';

function Demo() {
  return <TreeSelect label="Tree Select" placeholder="Tree Select" data={data} success="Looks good!" />;
}

Get element ref

import { useRef } from 'react';
import { TreeSelect } from '@mantine/core';

function Demo() {
  const ref = useRef<HTMLInputElement>(null);
  return <TreeSelect ref={ref} />;
}

Accessibility

If TreeSelect is used without the label prop, it will not be announced properly by screen readers:

import { TreeSelect } from '@mantine/core';

// Inaccessible input – screen reader will not announce it properly
function Demo() {
  return <TreeSelect />;
}

Set aria-label to make the input accessible. In this case the label will not be visible, but screen readers will announce it:

import { TreeSelect } from '@mantine/core';

// Accessible input – it has aria-label
function Demo() {
  return <TreeSelect aria-label="My input" />;
}

If the label prop is set, the input will be accessible and it is not required to set aria-label:

import { TreeSelect } from '@mantine/core';

// Accessible input – it has associated label element
function Demo() {
  return <TreeSelect label="My input" />;
}

When clearable is set, use clearButtonProps to set aria-label on the clear button:

import { TreeSelect } from '@mantine/core';

function Demo() {
  return (
    <TreeSelect
      data={[]}
      clearable
      clearButtonProps={{
        'aria-label': 'Clear input',
      }}
    />
  );
}