# Cascader

- Page: https://jiguang132.com/resources/mantine/docs/cascader
- 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 a value from hierarchical 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 |
| --- | --- |
| `Cascader.label` | Visible label or component-specific label content. |
| `Cascader.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

Demo content/state is local, without server persistence, authorization or fetching. A static display component is not a completed business workflow.

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


function ComponentPreview({ variant = 'Default' }: { variant?: string }) {
const [value, setValue] = useState(35);
return <M.Cascader label="Location" data={[{ value: "asia", label: "Asia", children: [{ value: "china", label: "China" }] }]} />;
}
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

`Cascader` lets users select a value from hierarchical data: picking an option in one column
reveals its children in the next column. The value is a path from the root option to the
selected one, for example `['asia', 'jp', 'tokyo']`.

All demos on this page switch to the [flat list layout](#flat-list-layout) on small screens,
open them on a larger screen to see the columns.



## Data prop

Data passed to the `data` prop is an array of `CascaderOption` objects:

- Each option must have a unique `value` across the whole data tree
- `label` is optional, `value` is used when it is not set
- `children` contains an array of nested options
- `disabled` prevents an option from being selected or expanded

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

const data: CascaderOption[] = [
  {
    value: 'asia',
    label: 'Asia',
    children: [
      {
        value: 'jp',
        label: 'Japan',
        children: [{ value: 'tokyo', label: 'Tokyo' }],
      },
    ],
  },
];
```

## Value and onChange

`Cascader` value is an array of option values or `null` when nothing is selected.
`onChange` is called with the selected path and the corresponding `CascaderOption` objects:

```tsx
import { useState } from 'react';
import { Cascader, CascaderOption } from '@mantine/core';

function Demo() {
  const [value, setValue] = useState<string[] | null>(['europe', 'fr', 'paris']);

  const handleChange = (path: string[] | null, options: CascaderOption[]) => {
    setValue(path);
    console.log(path, options);
  };

  return <Cascader data={data} value={value} onChange={handleChange} />;
}
```

By default, only leaf options (options without children) can be selected. Clicking a parent
option only expands the next column.

## Change on select

Set the `changeOnSelect` prop to allow selecting any option, not only leaves. Clicking a parent
option then both selects it and expands the next column:



## Close on select

`closeOnSelect` controls whether the dropdown is closed after a value is selected. By default,
the dropdown stays open, unless [allowDeselect](#allow-deselect) is set to `false`:



## Allow deselect

By default, clicking the selected option again removes the value. Set `allowDeselect={false}` to
disable this behavior:



## Expand trigger

By default, the next column is opened when an option is clicked. Set `expandTrigger="hover"`
to open the next column on hover instead – selecting a leaf still requires a click:



With `expandTrigger="hover"`, the open column stays in place while the cursor moves diagonally
toward it. Set `safeAreaPolygon={false}` to disable this behavior, or pass an object to configure
[Floating UI `safePolygon`](https://floating-ui.com/docs/useHover#safepolygon) options:



## Flat list layout

Columns require horizontal space and do not fit narrow screens. Set `withColumns={false}`
to render options as a flat list of full paths instead:



Combine `withColumns` with the [use-matches](/hooks/use-matches/) hook to render columns
on desktop and the flat list on mobile:

```tsx
import { Cascader, useMatches } from '@mantine/core';

function Demo() {
  const withColumns = useMatches({ base: false, sm: true });
  return <Cascader withColumns={withColumns} data={data} />;
}
```

## Max displayed levels

Use the `maxDisplayedLevels` prop (`3` by default) to limit the number of columns displayed
next to each other. When the limit is exceeded, the first columns are hidden and a control
to reveal them is displayed on the left:



## Searchable

Set the `searchable` prop to allow filtering options. In search mode, the columns are replaced
with a flat list of full paths that match the query:



Use the `filter` prop to customize how paths are matched and `renderSearchOption` to customize
how search results are rendered:

```tsx
import { Cascader, CascaderOption } from '@mantine/core';

function Demo() {
  return (
    <Cascader
      searchable
      data={data}
      filter={(query, options: CascaderOption[]) =>
        options.some((option) => String(option.label).toLowerCase().includes(query.toLowerCase()))
      }
      renderSearchOption={(query, options) => options.map((option) => option.label).join(' → ')}
    />
  );
}
```

## Controlled search value

Use `searchValue` and `onSearchChange` props to control the search value:

```tsx
import { useState } from 'react';
import { Cascader } from '@mantine/core';

function Demo() {
  const [searchValue, setSearchValue] = useState('');
  return (
    <Cascader
      searchable
      data={data}
      searchValue={searchValue}
      onSearchChange={setSearchValue}
    />
  );
}
```

## Nothing found

Set the `nothingFoundMessage` prop to display a message when no options match the search query:



## Display value

By default, the selected path is displayed in the input as option labels joined by the `separator`
(`/` by default). Use the `separator` prop to change the divider and the `formatValue` prop to
fully customize the input label:



## Column width

Use the `columnWidth` prop to set a fixed width for every column and `maxDropdownHeight`
(`260` by default) to set the max height of a column:



## Custom option rendering

Use the `renderOption` prop to customize how options are rendered in columns. The function receives
the option and its column level:



## Check icon

Use the `withCheckIcon` prop to toggle the check icon on the selected option and `checkIconPosition`
to change its position (`left` or `right`):



## Disabled options

Set the `disabled` property on an option to prevent it from being selected or expanded. Disabled
options are skipped during keyboard navigation:



## Left and right sections

`Cascader` supports `leftSection` and `rightSection` props the same way as other inputs:



## Clearable

Set the `clearable` prop to display the clear button when a value is selected:



Use the `clearSectionMode` prop to control how the clear button and `rightSection` are rendered:



## Scrollable columns

Each column is scrollable. Use `scrollAreaProps` to pass props down to the
[ScrollArea](/core/scroll-area) of each column:



## Control dropdown opened state

Use `dropdownOpened`, `defaultDropdownOpened`, `onDropdownOpen` and `onDropdownClose` props to
control the dropdown opened state:

```tsx
import { useState } from 'react';
import { Cascader } from '@mantine/core';

function Demo() {
  const [dropdownOpened, setDropdownOpened] = useState(false);
  return (
    <Cascader
      data={data}
      dropdownOpened={dropdownOpened}
      onDropdownOpen={() => setDropdownOpened(true)}
      onDropdownClose={() => setDropdownOpened(false)}
    />
  );
}
```

## Dropdown position

Use `comboboxProps` to pass props down to the underlying [Combobox](/core/combobox) and
[Popover](/core/popover). For example, set `position` to change the dropdown position:



## Dropdown offset



## Dropdown width

In flat list mode (`withColumns={false}`) the dropdown width can be controlled with
`comboboxProps={{ width }}`. In columns mode the dropdown is sized to the columns:



## Dropdown padding



## Dropdown shadow



## Dropdown animation



## Inside Popover

To use `Cascader` inside a `Popover`, set `comboboxProps={{ withinPortal: false }}`:




## Styles API

Use the [Styles API](/styles/styles-api/) to customize `Cascader` styles:




## Input props




## Read only

Set `readOnly` to make the input read only. When `readOnly` is set, `Cascader` will not open the
dropdown 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 `Cascader` will not open the dropdown.



## Error state



## Success state



## Loading state

Set the `loading` prop to display a loader in the right section instead of the chevron:



## Accessibility

`Cascader` columns are rendered as nested listboxes with `option` elements. To make the component
accessible, set the `label` prop or pass `aria-label` to the component:

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

// Set aria-label when the input does not have a visible label
function Demo() {
  return <Cascader data={data} aria-label="Pick location" />;
}
```

## Keyboard interactions



## 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
Cascader(_props)
```



```ts
export interface CascaderOption {
  /** Option value, must be unique across the whole data tree */
  value: string;

  /** Option label, if not set `value` is used instead */
  label?: React.ReactNode;

  /** Nested options */
  children?: CascaderOption[];

  /** If set, the option cannot be selected or expanded */
  disabled?: boolean;
}

export interface CascaderFormatValueInput {
  /** Selected path from root to node */
  value: string[];

  /** Option chain resolved from the selected path */
  options: CascaderOption[];
}

export type CascaderFormatValue = (input: CascaderFormatValueInput) => React.ReactNode;

export type CascaderSafeAreaPolygonOptions = Omit<SafePolygonOptions, 'blockPointerEvents'>;

export type CascaderStylesNames =
  | __InputStylesNames
  | ComboboxLikeStylesNames
  | 'columnsList'
  | 'columnsOverflow'
  | 'column'
  | 'columnScroll'
  | 'columnOption'
  | 'columnOptionLabel'
  | 'columnOptionIcon'
  | 'columnOptionCheck'
  | 'columnEmpty'
  | 'flatOption';

export interface CascaderProps
  extends
    BoxProps,
    __BaseInputProps,
    StylesApiProps<CascaderFactory>,
    ElementProps<'input', 'size' | 'value' | 'defaultValue' | 'onChange'> {
  /** Hierarchical options data */
  data: CascaderOption[];

  /** Controlled selected path from root to node */
  value?: string[] | null;

  /** Uncontrolled selected path from root to node */
  defaultValue?: string[] | null;

  /** Called when the selected path changes with the path and the resolved option chain */
  onChange?: (value: string[] | null, options: CascaderOption[]) => void;

  /** If set, any intermediate option can be selected, not only leaf options @default false */
  changeOnSelect?: boolean;

  /** Determines whether the dropdown should be closed when a value is selected, defaults to `!allowDeselect` */
  closeOnSelect?: boolean;

  /** If set, the selected value can be deselected by selecting it again @default true */
  allowDeselect?: boolean;

  /** If set, the check icon is displayed on the selected option @default true */
  withCheckIcon?: boolean;

  /** Position of the check icon relative to the option label @default 'right' */
  checkIconPosition?: 'left' | 'right';

  /** Renders the dropdown as cascading columns. When `false`, options are rendered as a flat list of paths, the same way as search results (useful for narrow/mobile layouts) @default true */
  withColumns?: boolean;

  /** Determines how the next column is opened @default 'click' */
  expandTrigger?: 'click' | 'hover';

  /** Determines whether the next column stays open while the cursor moves toward it, applicable only when `expandTrigger="hover"`. Pass an object to configure safe polygon behavior. @default true */
  safeAreaPolygon?: boolean | CascaderSafeAreaPolygonOptions;

  /** If set, options can be searched by their flattened paths @default false */
  searchable?: boolean;

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

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

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

  /** Custom search filter, matched against the full option path */
  filter?: (query: string, options: CascaderOption[]) => boolean;

  /** Custom rendering of a search result row */
  renderSearchOption?: (query: string, options: CascaderOption[]) => React.ReactNode;

  /** A function to format the selected path displayed in the input, should return a string */
  formatValue?: CascaderFormatValue;

  /** Custom rendering of an option in columns */
  renderOption?: (option: CascaderOption, level: number) => React.ReactNode;

  /** Path separator displayed in the input and search results @default '/' */
  separator?: React.ReactNode;

  /** Width of each column */
  columnWidth?: number | string;

  /** Maximum number of columns (levels) displayed next to each other, deeper levels replace earlier ones @default 3 */
  maxDisplayedLevels?: number;

  /** `aria-label` and `title` of the control that reveals levels hidden before the visible ones by `maxDisplayedLevels` @default 'Show previous levels' */
  previousLevelsControlLabel?: string;

  /** `aria-label` and `title` of the control that reveals levels hidden after the visible ones by `maxDisplayedLevels` @default 'Show next levels' */
  nextLevelsControlLabel?: string;

  /** Max height of a column before it becomes scrollable @default 260 */
  maxDropdownHeight?: number | string;

  /** Message displayed when there are no options or search results */
  nothingFoundMessage?: React.ReactNode;

  /** If set, the clear button is displayed when a value is selected @default false */
  clearable?: boolean;

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

  /** Props passed down to the clear button */
  clearButtonProps?: InputClearButtonProps;

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

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

  /** Uncontrolled dropdown opened state */
  defaultDropdownOpened?: boolean;

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

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

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

  /** Props passed down to the dropdown `ScrollArea` */
  scrollAreaProps?: ScrollAreaProps;

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

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

  /** Opens the dropdown when the input is focused in `searchable` mode @default true */
  openOnFocus?: boolean;
}

export type CascaderFactory = Factory<{
  props: CascaderProps;
  ref: HTMLInputElement;
  stylesNames: CascaderStylesNames;
  variant: InputVariant;
}>;

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: CascaderProps;
  ref: HTMLInputElement;
  stylesNames: CascaderStylesNames;
  variant: InputVariant;
}>
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<CascaderFactory>
React.ElementType
Omit<React.ComponentProps<ElementType>, 'style' | PropsToOmit>
React.ComponentProps<ElementType>
ElementType
PropsToOmit
Omit<SafePolygonOptions, 'blockPointerEvents'>
SafePolygonOptions
InputClearButtonProps
ScrollAreaProps
MantineColor
Omit<React.ComponentProps<'input'>, 'value'>
React.ComponentProps<'input'>
HTMLInputElement
InputLabelStylesNames
InputDescriptionStylesNames
InputErrorStylesNames
InputSuccessStylesNames
ComboboxLikeStylesNames
```

---

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