# 树形选择

- 页面: https://jiguang132.com/zh/resources/mantine/docs/tree-select
- 资源: Mantine Core (https://jiguang132.com/zh/resources/mantine.md)
- 全部指南: https://jiguang132.com/zh/resources/mantine/docs.md

Mantine Core 的独立组件，请不要替换为 JGuang UI/Base UI 的同名 API。

## 安装

```bash
npm install @mantine/core@9.7.1 @mantine/hooks@9.7.1
```

入口引入 `@mantine/core/styles.css`，并在根组件使用 `MantineProvider`；通过 `forceColorScheme` 同步深浅色主题。

## 使用与验证

在左侧选择组件，在预览中操作它的状态；使用“查看代码”检查真实源码。安装后执行类型检查和构建，再验证键盘焦点、手机布局与深浅色主题。

## 来源

https://github.com/mantinedev/mantine/tree/f0e2bc6d28b0f0b8aaefb5b859937bf77f539df7
MIT 许可证；不包括付费内容。下方提供上游英文参考内容，中文使用指南已适配；上游详细参考暂保留英文。

---


## 版本与兼容性

固定的 Mantine Core 9.7.1 要求 React 和 React DOM 满足 `^19.2.0`，并配套 `@mantine/hooks@9.7.1`。此条件来自实际 npm 包的 peerDependencies。React 18 或其他不兼容版本不能强行安装；先向项目负责人说明升级影响并确认方案，不使用 --force/--legacy-peer-deps 掩盖冲突。入口的原生 Provider 开启 `theme.respectReducedMotion`，并用 `forceColorScheme` 控制深浅色。

## 适用场景

从树形选项中选择值。

## 本地示例使用的原生参数

以下参数由本地、经过类型检查的 JSX 示例提取，按所属组件区分。不是全部属性清单；完整签名和继承关系见下方固定源码参考。

| 组件参数 | 说明 |
| --- | --- |
| `TreeSelect.label` | 可见标签或当前组件的标签内容。 |
| `TreeSelect.data` | 本地选项或节点，保持 value 唯一并遵循原生结构。 |

## 交互与状态检查

当前场景：默认。切换支持的禁用、错误或只读场景后检查真实行为；无此原生状态的组件不会被强行添加统一属性。验证键盘焦点和退出方式，修改值后按原生回调签名连接业务状态。

## 业务接入边界

选择值类型随 single/multiple/checkbox 模式变化；保留泛型模式与值之间的关系。

## 宿主配置

先安装固定版本 @mantine/core 和 @mantine/hooks，在入口引入 @mantine/core/styles.css，并使用 MantineProvider。示例的 theme 和 variant 是 JGuang 编写的宿主参数，不是所有原生组件都接受的统一 API；通过 forceColorScheme 同步应用主题。源码面板中的原生实现仅供阅读，使用 npm 导出，不要单独复制内部实现。此批只覆盖 Core，不包括日期、图表和表单扩展包。上游详细说明保留英文，不宣称全文中文化。


## 可运行用法

以下代码使用资源原生 API；不是把其他设计系统的同名组件替换进来。

```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>;
}

```


## 可用状态与示例

默认

示例遵循 Mantine 原生 API。支持多状态的输入组件可将示例中的 variant 改为 Disabled、Invalid 或 Read only；这些只是示例标签，不是新增的组件属性。改造时保留组件要求的数据、受控值、store 和复合子组件结构。


## 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',
      }}
    />
  );
}
```


## 源码参数参考

以下实现签名和类型从本地固定版本源码生成。保留可选属性、原生继承类型、联合分支和 never 限制；不会将其他设计系统的 API 混入。forwardRef 实现中的 ref 属于 React 引用，不是新增业务属性。此区域是原始类型参考，不是上游说明的全文翻译。


```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')[];
}
```


### 原生与外部类型

以下外部类型仍由 React 或资源自身依赖定义，没有手工展开为虚构属性。实际可用类型以安装版本的 TypeScript 检查为准。


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

---

JGuang 全部资源索引: https://jiguang132.com/llms.txt