# TreeSelect

- Page: https://jiguang132.com/resources/mantine/docs/tree-select
- Resource: Mantine Core (https://jiguang132.com/resources/mantine.md)
- All guides: https://jiguang132.com/resources/mantine/docs.md

Install: `npm install @mantine/core@9.7.1 @mantine/hooks@9.7.1`

## Version and compatibility

Pinned Mantine Core 9.7.1 requires React and React DOM `^19.2.0` and matching `@mantine/hooks@9.7.1`, from the installed npm package's peerDependencies. Do not force it into React 18 or another incompatible version. Explain upgrade impact and agree on a plan with the project owner; do not hide conflicts with --force/--legacy-peer-deps. The native Provider enables `theme.respectReducedMotion` and uses `forceColorScheme` for light/dark.

## Use case

Choose values from a tree of options.

## Native props used by this example

These props are extracted from the local typechecked JSX and grouped by their owning native component. This is not an exhaustive prop list; see pinned source signatures and inheritance below.

| Component prop | Explanation |
| --- | --- |
| `TreeSelect.label` | Visible label or component-specific label content. |
| `TreeSelect.data` | Local options/nodes; keep unique values and native schema. |

## Interaction and state checks

Current scenarios: Default. Check actual behavior after selecting supported disabled/error/read-only scenarios; components without those native states do not receive invented universal props. Verify keyboard focus and exits, then connect changed values through the native callback signature.

## Business integration boundary

Selection type depends on single/multiple/checkbox mode; preserve the generic mode/value relationship.

## Host setup

Install pinned @mantine/core and @mantine/hooks, import @mantine/core/styles.css at the entry and use MantineProvider. The example's theme/variant are JGuang-authored host props, not universal native component APIs; forceColorScheme synchronizes the app theme. Native implementation source is a reading reference: use npm exports rather than copying internal engines. This batch covers Core, not dates/charts/forms extension packages. Detailed upstream prose remains English.


## Runnable usage

```tsx
import { useState } from 'react';
import * as M from '@mantine/core';
import '@mantine/core/styles.css';

const tree = [{ value: "src", label: "src", children: [{ value: "components", label: "components" }, { value: "styles", label: "styles" }] }];
function ComponentPreview({ variant = 'Default' }: { variant?: string }) {
const [value, setValue] = useState(35);
return <M.TreeSelect label="Files" data={tree} />;
}
export default function Example({ variant = 'Default', theme = 'light' }: { variant?: string; theme?: 'light' | 'dark' }) {
return <M.MantineProvider forceColorScheme={theme} theme={{ respectReducedMotion: true }}><ComponentPreview variant={variant} /></M.MantineProvider>;
}

```


## Preview states

Default

The example uses the native Mantine API. For supported input demos, change the local variant to Disabled, Invalid or Read only; these are example labels, not new component props. Keep the documented data, controlled values, stores and compound children when adapting the example.



## Usage

`TreeSelect` allows picking one or more values from hierarchical tree data.
It supports three selection modes: single, multiple, and checkbox (with parent-child cascade).



## Data prop

Data passed to the `data` prop must follow the same rules as the [Tree](/core/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

```tsx
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



### 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.



## Controlled

```tsx
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 the `searchable` prop to allow filtering options by user input.
When searching, matching nodes and their ancestors are shown:



## Nothing found

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



## Clearable

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



## Expand on click

Set the `expandOnClick` prop to also toggle expansion when clicking a parent node
(in addition to the chevron). Behavior depends on the selection mode:

- `single` and `multiple` – clicking a parent only expands/collapses it. Only leaf nodes can be selected.
- `checkbox` – clicking a parent both toggles its checked state and expands it.



## Connecting lines

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



## Check strictly

Set `checkStrictly` to disable parent-child cascade in checkbox mode.
Each node's checked state becomes fully independent:



## Checked strategy

The `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



## Max values

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



## renderNode

Use the `renderNode` callback to customize node rendering in the dropdown. It is called
with the node and its state:



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



## renderPill

Use the `renderPill` callback to customize pills of selected values in `multiple` and
`checkbox` modes. Call `onRemove` from your pill to remove the value.

`renderPill` is not called for the overflow pill displayed when the number of selected values
exceeds `maxDisplayedValues`, use `maxDisplayedValuesContent` to customize it instead.



## Scrollable dropdown

By default, the options list is wrapped with [ScrollArea.Autosize](/core/scroll-area).
You can control the dropdown max-height with the `maxDropdownHeight` prop:




## Control dropdown opened state

You can control the dropdown opened state with the `dropdownOpened` prop. Additionally,
you can use `onDropdownClose` and `onDropdownOpen` to listen to dropdown opened state changes.



## Dropdown position

By default, the dropdown is displayed below the input if there is enough space; otherwise it is displayed above the input.
You can change this behavior by setting the `position` and `middlewares` props, which are passed down to the
underlying [Popover](/core/popover) component.

Example of a dropdown that is always displayed above the input:



## Dropdown width

To change the dropdown width, set the `width` prop in `comboboxProps`. By default,
the dropdown width is equal to the input width.



## Dropdown offset

To change the dropdown offset, set the `offset` prop in `comboboxProps`:



## Dropdown animation

By default, dropdown animations are disabled. To enable them, you can set `transitionProps`,
which will be passed down to the underlying [Transition](/core/transition) component.



## Dropdown padding



## Dropdown shadow



## 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

You can control the expanded state of nodes:

```tsx
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}
/>
```




## Input props




## Read only

Set `readOnly` to make the input read only. When `readOnly` is set,
`TreeSelect` will not show suggestions and will not call the `onChange` function.



## Disabled

Set `disabled` to disable the input. When `disabled` is set,
the user cannot interact with the input and `TreeSelect` will not show suggestions.



## Error state



## Success state





To set `aria-label` on the clear button, use `clearButtonProps`. Note that this is required
only when `clearable` is set.

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

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


## Source-backed parameter reference

Implementation signatures and types are generated from the pinned local source. Optional props, native inherited types, union branches and never exclusions are preserved. A forwardRef implementation's ref is a React reference, not an additional business prop.


```ts
TreeSelect(_props)
```



```ts
export type TreeSelectStylesNames =
  | __InputStylesNames
  | ComboboxLikeStylesNames
  | 'pill'
  | 'pillsList'
  | 'inputField';

export type TreeSelectMode = 'single' | 'multiple' | 'checkbox';

export type TreeSelectValue<Mode extends TreeSelectMode> = Mode extends 'single'
  ? string | null
  : string[];

export interface TreeSelectRenderPillPayload {
  /** Node associated with the pill. If the value is not present in `data`, a placeholder node with `label` equal to the value is passed. */
  node: TreeNodeData;

  /** Selected value that the pill represents */
  value: string;

  /** Removes the value from the selection. In `checkbox` mode unchecks the node and, unless `checkStrictly` is set, all its children, same as the default pill remove button. */
  onRemove: () => void;

  /** Value of the `disabled` prop passed to the component */
  disabled?: boolean;

  /** Value of the `readOnly` prop passed to the component */
  readOnly?: boolean;
}

export interface TreeSelectProps<Mode extends TreeSelectMode = 'single'>
  extends
    BoxProps,
    __BaseInputProps,
    StylesApiProps<TreeSelectFactory>,
    ElementProps<'input', 'size' | 'value' | 'defaultValue' | 'onChange'> {
  /** Tree data */
  data: TreeNodeData[];

  /** Selection mode: 'single', 'multiple', or 'checkbox' (with cascade) @default 'single' */
  mode?: Mode;

  /** Controlled value */
  value?: TreeSelectValue<Mode>;

  /** Default value */
  defaultValue?: TreeSelectValue<Mode>;

  /** Called when value changes */
  onChange?: (value: TreeSelectValue<Mode>) => void;

  /** Disables parent-child cascade in checkbox mode @default false */
  checkStrictly?: boolean;

  /** Controls which checked nodes appear in value/pills in checkbox mode @default 'child' */
  checkedStrategy?: CheckedStrategy;

  /** Default expanded node values */
  defaultExpandedValues?: string[];

  /** Expand all nodes by default @default false */
  defaultExpandAll?: boolean;

  /** Controlled expanded state */
  expandedValues?: string[];

  /** Called when expanded state changes */
  onExpandedChange?: (values: string[]) => void;

  /** Also toggle expand when clicking a parent node (not just the chevron). In `single` and `multiple` modes, parent clicks only expand; only leaves can be selected. In `checkbox` mode, parent clicks both check and expand. @default false */
  expandOnClick?: boolean;

  /** Enables search filtering @default false */
  searchable?: boolean;

  /** Controlled search value */
  searchValue?: string;

  /** Default search value */
  defaultSearchValue?: string;

  /** Called when search changes */
  onSearchChange?: (value: string) => void;

  /** Custom filter function */
  filter?: (query: string, node: TreeNodeData) => boolean;

  /** Message when no nodes match search */
  nothingFoundMessage?: React.ReactNode;

  /** Allows deselecting in single mode @default true */
  allowDeselect?: boolean;

  /** Shows clear button @default false */
  clearable?: boolean;

  /** Determines how the clear button and rightSection are rendered @default 'both' */
  clearSectionMode?: ClearSectionMode;

  /** Props for the clear button */
  clearButtonProps?: InputClearButtonProps;

  /** Maximum selectable values (multiple/checkbox mode) */
  maxValues?: number;

  /** Maximum displayed pills before "+N more" */
  maxDisplayedValues?: number;

  /** Content shown when values overflow maxDisplayedValues */
  maxDisplayedValuesContent?: React.ReactNode | ((overflow: number) => React.ReactNode);

  /** Called with removed value in multiple/checkbox mode */
  onRemove?: (value: string) => void;

  /** Called when clear button is clicked */
  onClear?: () => void;

  /** Custom node rendering in the dropdown */
  renderNode?: (payload: TreeSelectRenderNodePayload) => React.ReactNode;

  /** Custom pill rendering in `multiple` and `checkbox` modes. Not called for the overflow pill displayed when `maxDisplayedValues` is exceeded. */
  renderPill?: (payload: TreeSelectRenderPillPayload) => React.ReactNode;

  /** Show tree connection lines between parent and child nodes @default true */
  withLines?: boolean;

  /** Props for the hidden input */
  hiddenInputProps?: Omit<React.ComponentProps<'input'>, 'value'>;

  /** Divider for hidden input values @default ',' */
  hiddenInputValuesDivider?: string;

  /** Props for the ScrollArea in the dropdown */
  scrollAreaProps?: ScrollAreaProps;

  /** Controls the default chevron color */
  chevronColor?: MantineColor;

  /** Max dropdown height @default 220 */
  maxDropdownHeight?: number | string;

  /** Controlled dropdown state */
  dropdownOpened?: boolean;

  /** Default dropdown state */
  defaultDropdownOpened?: boolean;

  /** Called when dropdown opens */
  onDropdownOpen?: () => void;

  /** Called when dropdown closes */
  onDropdownClose?: () => void;

  /** Props passed to the underlying Combobox */
  comboboxProps?: Record<string, any>;

  /** Clear search on selection change @default true */
  clearSearchOnChange?: boolean;

  /** Opens dropdown on focus (searchable mode) @default true */
  openOnFocus?: boolean;

  /** aria-label values for the expand/collapse chevron button */
  chevronAriaLabels?: TreeSelectChevronAriaLabels;
}

export type TreeSelectFactory = Factory<{
  props: TreeSelectProps;
  ref: HTMLInputElement;
  stylesNames: TreeSelectStylesNames;
  variant: InputVariant;
  signature: <Mode extends TreeSelectMode = 'single'>(
    props: TreeSelectProps<Mode>
  ) => React.JSX.Element;
}>;

export type Mod = Record<string, any> | string;

export type BoxMod = Mod | Mod[] | BoxMod[];

export interface BoxProps extends MantineStyleProps {
  /** Class added to the root element, if applicable */
  className?: string | undefined;

  /** Inline style added to root component element, can subscribe to theme defined on MantineProvider */
  style?: MantineStyleProp;

  /** CSS variables defined on root component element */
  __vars?: CssVarsProp;

  /** `size` property passed down the HTML element */
  __size?: string;

  /** Breakpoint above which the component is hidden with `display: none` */
  hiddenFrom?: MantineBreakpoint;

  /** Breakpoint below which the component is hidden with `display: none` */
  visibleFrom?: MantineBreakpoint;

  /** Determines whether component should be hidden in light color scheme with `display: none` */
  lightHidden?: boolean;

  /** Determines whether component should be hidden in dark color scheme with `display: none` */
  darkHidden?: boolean;

  /** Element modifiers transformed into `data-` attributes, for example, `{ 'data-size': 'xl' }`, falsy values are removed */
  mod?: BoxMod;
}

export type ElementProps<
  ElementType extends React.ElementType,
  PropsToOmit extends string = never,
> = Omit<React.ComponentProps<ElementType>, 'style' | PropsToOmit>;

export interface CSSProperties extends React.CSSProperties {
  [key: string]: any;
}

type MantineStyle = CSSProperties | ((theme: MantineTheme) => CSSProperties);

export type MantineStyleProp = MantineStyle | MantineStyle[] | MantineStyleProp[] | undefined;

export type CssVariable = `--${string}`;

export type CssVariables<Variable extends string = CssVariable> = Partial<Record<Variable, string>>;

export type CssVars<Variable extends string = CssVariable> =
  | CssVariables<Variable>
  | ((theme: MantineTheme) => CssVariables<Variable>)
  | CssVars<Variable>[];

export type CssVarsProp<Variable extends string = CssVariable> =
  | CssVars<Variable>
  | CssVars<Variable>[];

type WrapperProps = React.ComponentProps<'div'> & DataAttributes;

export interface __BaseInputProps extends __InputWrapperProps, __InputProps {
  /** Props passed down to the root element */
  wrapperProps?: WrapperProps;
}

export type __InputStylesNames = InputStylesNames | InputWrapperStylesNames;

export type InputStylesNames = 'input' | 'wrapper' | 'section' | 'bottomSection';

export type InputVariant = 'default' | 'filled' | 'unstyled';

export interface __InputProps {
  /** Content section displayed on the left side of the input */
  leftSection?: React.ReactNode;

  /** Left section width, used to set `width` of the section and input `padding-left`, by default equals to the input height */
  leftSectionWidth?: React.CSSProperties['width'];

  /** Props passed down to the `leftSection` element */
  leftSectionProps?: React.ComponentProps<'div'>;

  /** Sets `pointer-events` styles on the `leftSection` element. Use `'all'` when section contains interactive elements (buttons, links). @default 'none' */
  leftSectionPointerEvents?: React.CSSProperties['pointerEvents'];

  /** Content section displayed on the right side of the input */
  rightSection?: React.ReactNode;

  /** Right section width, used to set `width` of the section and input `padding-right`, by default equals to the input height */
  rightSectionWidth?: React.CSSProperties['width'];

  /** Props passed down to the `rightSection` element */
  rightSectionProps?: React.ComponentProps<'div'>;

  /** Sets `pointer-events` styles on the `rightSection` element. Use `'all'` when section contains interactive elements (buttons, links). @default 'none' */
  rightSectionPointerEvents?: React.CSSProperties['pointerEvents'];

  /** Sets `required` attribute on the `input` element */
  required?: boolean;

  /** Key of `theme.radius` or any valid CSS value to set `border-radius`, numbers are converted to rem @default theme.defaultRadius */
  radius?: MantineRadius;

  /** Sets `disabled` attribute on the `input` element */
  disabled?: boolean;

  /** Controls input `height`, horizontal `padding`, and `font-size` @default 'sm' */
  size?: MantineSize | (string & {});

  /** Determines whether the input should have `cursor: pointer` style. Use when input acts as a button-like trigger (e.g., `component="button"` for Select/DatePicker). @default false */
  pointer?: boolean;

  /** Determines whether the input should have red border and red text color when the `error` prop is set @default true */
  withErrorStyles?: boolean;

  /** Determines whether the input should have green border when the `success` prop is set @default true */
  withSuccessStyles?: boolean;

  /** HTML `size` attribute for the input element (number of visible characters) */
  inputSize?: string;

  /** Section to be displayed when the input is `__clearable` and `rightSection` is not defined */
  __clearSection?: React.ReactNode;

  /** Determines whether the `__clearSection` should be displayed if it is passed to the component, has no effect if `rightSection` is defined */
  __clearable?: boolean;

  /** Determines how the clear button and rightSection are rendered @default 'both' */
  __clearSectionMode?: ClearSectionMode;

  /** Right section displayed when both `__clearSection` and `rightSection` are not defined */
  __defaultRightSection?: React.ReactNode;

  /** Displays loading indicator in the left or right section @default false */
  loading?: boolean;

  /** Position of the loading indicator @default 'right' */
  loadingPosition?: 'left' | 'right';

  /** Content section displayed at the bottom of the input, inside the border */
  __bottomSection?: React.ReactNode;

  /** Props passed down to the `__bottomSection` element */
  __bottomSectionProps?: React.ComponentProps<'div'>;
}

export type InputWrapperStylesNames =
  | 'root'
  | InputLabelStylesNames
  | InputDescriptionStylesNames
  | InputErrorStylesNames
  | InputSuccessStylesNames;

export interface __InputWrapperProps {
  /** Contents of `Input.Label` component. If not set, label is not displayed. */
  label?: React.ReactNode;

  /** Contents of `Input.Description` component. If not set, description is not displayed. */
  description?: React.ReactNode;

  /** Contents of `Input.Error` component. If not set, error is not displayed. */
  error?: React.ReactNode;

  /** Contents of `Input.Success` component. If not set, success is not displayed. */
  success?: React.ReactNode;

  /** Adds required attribute to the input and a red asterisk on the right side of label @default false */
  required?: boolean;

  /** If set, the required asterisk is displayed next to the label. Overrides `required` prop. Does not add required attribute to the input. @default false */
  withAsterisk?: boolean;

  /** Props passed down to the `Input.Label` component */
  labelProps?: InputLabelProps & DataAttributes & PlaceholderPolymorphicProps;

  /** Props passed down to the `Input.Description` component */
  descriptionProps?: InputDescriptionProps & DataAttributes & PlaceholderPolymorphicProps;

  /** Props passed down to the `Input.Error` component */
  errorProps?: InputErrorProps & DataAttributes & PlaceholderPolymorphicProps;

  /** Props passed down to the `Input.Success` component */
  successProps?: InputSuccessProps & DataAttributes & PlaceholderPolymorphicProps;

  /** Render function to wrap the input element. Useful for adding tooltips, popovers, or other wrappers around the input. @default React.Fragment */
  inputContainer?: (children: React.ReactNode) => React.ReactNode;

  /** Controls order and visibility of wrapper elements. Only elements included in this array will be rendered. @default ['label', 'description', 'input', 'error'] */
  inputWrapperOrder?: ('label' | 'input' | 'description' | 'error')[];
}
```


### Native and external types

External types remain defined by React or native dependencies, not manually expanded into guessed props. The installed version's TypeScript definitions are authoritative.


```ts
Factory<{
  props: TreeSelectProps;
  ref: HTMLInputElement;
  stylesNames: TreeSelectStylesNames;
  variant: InputVariant;
  signature: <Mode extends TreeSelectMode = 'single'>(
    props: TreeSelectProps<Mode>
  ) => React.JSX.Element;
}>
MantineStyleProps
React.CSSProperties
MantineTheme
Partial<Record<Variable, string>>
Record<Variable, string>
Variable
MantineBreakpoint
Record<string, any>
React.ReactNode
InputLabelProps
DataAttributes
PlaceholderPolymorphicProps
InputDescriptionProps
InputErrorProps
InputSuccessProps
React.ComponentProps<'div'>
MantineRadius
MantineSize
ClearSectionMode
StylesApiProps<TreeSelectFactory>
React.ElementType
Omit<React.ComponentProps<ElementType>, 'style' | PropsToOmit>
React.ComponentProps<ElementType>
ElementType
PropsToOmit
TreeNodeData
Mode
CheckedStrategy
InputClearButtonProps
TreeSelectRenderNodePayload
Omit<React.ComponentProps<'input'>, 'value'>
React.ComponentProps<'input'>
ScrollAreaProps
MantineColor
TreeSelectChevronAriaLabels
HTMLInputElement
InputLabelStylesNames
InputDescriptionStylesNames
InputErrorStylesNames
InputSuccessStylesNames
ComboboxLikeStylesNames
React.JSX.Element
```

---

Index of all JGuang resources: https://jiguang132.com/llms.txt