# Cascader
Package: @mantine/core
Import: import { Cascader } from '@mantine/core';
Description: Select a path from hierarchical data with cascading columns

## 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']`.

Demos on this page switch to the [flat list layout](#flat-list-layout) on small screens:

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

function Demo() {
  // Switch to a flat list on small screens
  const withColumns = useMatches({ base: false, sm: true });
  return (
    <Cascader
      withColumns={withColumns}
      label="Location"
      placeholder="Pick location"
      data={data}
    />
  );
}
```


## Cascader with uncontrolled forms

Set `name` to submit the selected path as one comma-separated string of option values:

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

function Demo() {
  return (
    <form
      onSubmit={(event) => {
        event.preventDefault();
        const data = new FormData(event.currentTarget);
        console.log(data.get('location'));
      }}
    >
      <Cascader
        name="location"
        label="Location"
        data={[
          { value: 'fr', label: 'France', children: [{ value: 'paris', label: 'Paris' }] },
        ]}
        defaultValue={['fr', 'paris']}
      />
      <button type="submit">Submit</button>
    </form>
  );
}
```

## Data prop

`data` is an array of options. Each option must have a unique `value` across the whole tree, `children` contains nested options:

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

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

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

## Change on select

By default, only leaf options can be selected and clicking a parent option expands the next column. Set `changeOnSelect` to allow selecting any option:

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

function Demo() {
  const withColumns = useMatches({ base: false, sm: true });
  return (
    <Cascader
      withColumns={withColumns}
      changeOnSelect
      label="Location"
      placeholder="Pick any level"
      data={data}
    />
  );
}
```


## Close on select

By default, the dropdown stays open after a value is selected. Set `closeOnSelect` to close it when an option without children is selected:

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

function Demo() {
  const withColumns = useMatches({ base: false, sm: true });
  return (
    <Cascader
      withColumns={withColumns}
      closeOnSelect
      label="Location"
      placeholder="Pick location"
      data={data}
    />
  );
}
```


## Allow deselect

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

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

function Demo() {
  return (
    <Cascader
      label="Location"
      placeholder="Pick location"
      allowDeselect={false}
      defaultValue={['asia', 'jp', 'tokyo']}
      data={data}
    />
  );
}
```


## Expand trigger

Set `expandTrigger="hover"` to open the next column on hover instead of click. Selecting a leaf still requires a click:

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

function Demo() {
  const withColumns = useMatches({ base: false, sm: true });
  return (
    <Cascader
      withColumns={withColumns}
      expandTrigger="hover"
      label="Location"
      placeholder="Hover to expand"
      data={data}
    />
  );
}
```


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 with [safePolygon](https://floating-ui.com/docs/useHover#safepolygon) options:

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

function Demo() {
  const withColumns = useMatches({ base: false, sm: true });
  return (
    <Cascader
      withColumns={withColumns}
      expandTrigger="hover"
      safeAreaPolygon={false}
      label="Location"
      placeholder="Hover to expand"
      data={data}
    />
  );
}
```


## Flat list layout

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

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

function Demo() {
  return (
    <Cascader
      withColumns={false}
      searchable
      label="Location"
      placeholder="Pick location"
      nothingFoundMessage="Nothing found..."
      data={data}
    />
  );
}
```


Combine `withColumns` with the [use-matches](https://alpha.mantine.dev/llms/styles-responsive.md#use-matches-hook) 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} />;
}
```

## Virtualized dropdown

Use `virtualizer` for search results and the flat list shown when `withColumns={false}`. Search for a product to select its full path:

```tsx
import { Cascader } from '@mantine/core';
import { catalog } from './data';
import { VirtualList } from './VirtualList';

function Demo() {
  return (
    <Cascader
      label="Product"
      placeholder="Search by category or product"
      data={catalog}
      withColumns={false}
      searchable
      virtualizer={VirtualList}
    />
  );
}
```


## Max displayed levels

Use `maxDisplayedLevels` to limit the number of columns displayed next to each other. When the limit is exceeded, the first columns are hidden behind a control on the left:

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

function Demo() {
  const withColumns = useMatches({ base: false, sm: true });
  return (
    <Cascader
      withColumns={withColumns}
      maxDisplayedLevels={2}
      label="Location"
      placeholder="Pick location"
      defaultValue={['asia', 'jp', 'tokyo']}
      data={data}
    />
  );
}
```


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

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

function Demo() {
  const withColumns = useMatches({ base: false, sm: true });
  return (
    <Cascader
      withColumns={withColumns}
      searchable
      label="Location"
      placeholder="Search location"
      nothingFoundMessage="Nothing found..."
      data={data}
    />
  );
}
```


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:

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

function Demo() {
  return (
    <Cascader
      searchable
      label="Location"
      placeholder="Search location"
      nothingFoundMessage="Nothing found..."
      data={data}
    />
  );
}
```


## Display value

The input displays option labels joined by the `separator`. Use `formatValue` to fully customize the input label:

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

function Demo() {
  const withColumns = useMatches({ base: false, sm: true });
  return (
    <Cascader
      withColumns={withColumns}
      label="Location"
      placeholder="Pick location"
      separator="›"
      defaultValue={['asia', 'jp', 'tokyo']}
      formatValue={({ options }) => options.map((option) => option.label).join(' › ')}
      data={data}
    />
  );
}
```


## Column width

Use `columnWidth` to set a fixed width for every column and `maxDropdownHeight` to set the max height of a column:

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

function Demo() {
  const withColumns = useMatches({ base: false, sm: true });
  return (
    <Cascader
      withColumns={withColumns}
      columnWidth={140}
      maxDropdownHeight={200}
      label="Location"
      placeholder="Pick location"
      data={data}
    />
  );
}
```


## Custom option rendering

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

```tsx
import CA from 'country-flag-icons/react/3x2/CA';
import DE from 'country-flag-icons/react/3x2/DE';
import FR from 'country-flag-icons/react/3x2/FR';
import JP from 'country-flag-icons/react/3x2/JP';
import KR from 'country-flag-icons/react/3x2/KR';
import US from 'country-flag-icons/react/3x2/US';
import { Badge, Cascader, CascaderOption, CascaderProps, Group, useMatches } from '@mantine/core';
import { data } from './data';

const flags: Record<string, typeof JP> = { jp: JP, kr: KR, fr: FR, de: DE, us: US, ca: CA };

function CountryFlag({ country }: { country: string }) {
  const Flag = flags[country];
  return <Flag aria-hidden style={{ width: 18 }} />;
}

function countCities(option: CascaderOption): number {
  if (!option.children || option.children.length === 0) {
    return 1;
  }
  return option.children.reduce((acc, child) => acc + countCities(child), 0);
}

const renderCascaderOption: CascaderProps['renderOption'] = (option, level) => (
  <Group gap="xs" justify="space-between" wrap="nowrap" flex="1">
    <Group gap={6} wrap="nowrap">
      {level === 1 && <CountryFlag country={option.value} />}
      <span>{option.label}</span>
    </Group>
    {level === 0 && (
      <Badge size="xs" variant="default" flex="none">
        {countCities(option)} cities
      </Badge>
    )}
  </Group>
);

function Demo() {
  const withColumns = useMatches({ base: false, sm: true });
  return (
    <Cascader
      withColumns={withColumns}
      label="Location"
      placeholder="Pick location"
      renderOption={renderCascaderOption}
      columnWidth={240}
      data={data}
    />
  );
}
```


## Check icon

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

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

function Demo() {
  return (
    <Cascader
      checkIconPosition="left"
      label="Location"
      placeholder="Pick location"
      defaultValue={['asia', 'jp', 'tokyo']}
      data={data}
    />
  );
}
```


## Disabled options

Set `disabled` on an option to prevent it from being selected or expanded:

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

const data: CascaderOption[] = [
  {
    value: 'asia',
    label: 'Asia',
    children: [
      { value: 'jp', label: 'Japan', children: [{ value: 'tokyo', label: 'Tokyo' }] },
      { value: 'kr', label: 'South Korea', disabled: true },
    ],
  },
  { value: 'antarctica', label: 'Antarctica', disabled: true },
];

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


## Left and right sections

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

```tsx
import { MapPinIcon } from '@phosphor-icons/react';
import { Cascader, useMatches } from '@mantine/core';
import { data } from './data';

function Demo() {
  const withColumns = useMatches({ base: false, sm: true });
  return (
    <Cascader
      withColumns={withColumns}
      label="Location"
      placeholder="Pick location"
      leftSectionPointerEvents="none"
      leftSection={<MapPinIcon size={16} />}
      data={data}
    />
  );
}
```


## Clearable

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

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

function Demo() {
  const withColumns = useMatches({ base: false, sm: true });
  return (
    <Cascader
      withColumns={withColumns}
      clearable
      label="Location"
      placeholder="Pick location"
      defaultValue={['asia', 'jp', 'tokyo']}
      data={data}
    />
  );
}
```


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

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

function Demo() {
  return (
    <Cascader
      label="Location"
      placeholder="Pick location"
      clearable
      clearSectionMode="clear"
      defaultValue={['asia', 'jp', 'tokyo']}
      data={data}
    />
  );
}
```


## Scrollable columns

A column scrolls when its options are taller than `maxDropdownHeight`. Use `scrollAreaProps` to pass props down to the [ScrollArea](https://alpha.mantine.dev/llms/core-scroll-area.md) of each column:

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

function Demo() {
  return (
    <Cascader
      label="Location"
      placeholder="Pick location"
      defaultValue={['asia', 'jp', 'jp-city-3']}
      maxDropdownHeight={180}
      scrollAreaProps={{ type: 'always' }}
      data={data}
    />
  );
}
```


## 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](https://alpha.mantine.dev/llms/core-combobox.md) and [Popover](https://alpha.mantine.dev/llms/core-popover.md). For example, set `position` to change the dropdown position:

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

function Demo() {
  return (
    <Cascader
      label="Location"
      placeholder="Pick location"
      comboboxProps={{ position: 'top-start' }}
      data={data}
    />
  );
}
```


## Dropdown offset

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

function Demo() {
  return (
    <Cascader
      label="Location"
      placeholder="Pick location"
      comboboxProps={{ offset: 0 }}
      data={data}
    />
  );
}
```


## Dropdown width

In columns mode the dropdown is sized to the columns. In flat list mode, set the width with `comboboxProps={{ width }}`:

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

function Demo() {
  return (
    <Cascader
      withColumns={false}
      label="Location"
      placeholder="Pick location"
      comboboxProps={{ width: 220, position: 'bottom-start' }}
      data={data}
    />
  );
}
```


## Dropdown padding

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

// Dropdown padding is only applied to the flat list (withColumns={false});
// in columns mode each column manages its own padding.
function Demo() {
  return (
    <Cascader
      withColumns={false}
      label="Location"
      placeholder="Pick location"
      comboboxProps={{ dropdownPadding: 12 }}
      data={data}
    />
  );
}
```


## Dropdown shadow

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

function Demo() {
  return (
    <Cascader
      label="Location"
      placeholder="Pick location"
      comboboxProps={{ shadow: 'md' }}
      data={data}
    />
  );
}
```


## Dropdown animation

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

function Demo() {
  return (
    <Cascader
      label="Location"
      placeholder="Pick location"
      comboboxProps={{ transitionProps: { transition: 'pop', duration: 200 } }}
      data={data}
    />
  );
}
```


## Input props

Cascader component supports [Input](https://mantine.dev/core/input) and [Input.Wrapper](https://mantine.dev/core/input) components features and all input element props. Cascader documentation does not include all features supported by the component – see [Input](https://mantine.dev/core/input) documentation to learn about all available features.

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

function Demo() {
  const withColumns = useMatches({ base: false, sm: true });
  return (
    <Cascader
       variant="default" size="sm" radius="md" label="Input label" withAsterisk={false} description="Input description" error=""
      withColumns={withColumns}
      placeholder="Pick location"
      data={data}
    />
  );
}

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

export const data: CascaderOption[] = [
  {
    value: 'asia',
    label: 'Asia',
    children: [
      {
        value: 'jp',
        label: 'Japan',
        children: [
          { value: 'tokyo', label: 'Tokyo' },
          { value: 'osaka', label: 'Osaka' },
          { value: 'kyoto', label: 'Kyoto' },
        ],
      },
      {
        value: 'kr',
        label: 'South Korea',
        children: [
          { value: 'seoul', label: 'Seoul' },
          { value: 'busan', label: 'Busan' },
        ],
      },
    ],
  },
  {
    value: 'europe',
    label: 'Europe',
    children: [
      {
        value: 'fr',
        label: 'France',
        children: [
          { value: 'paris', label: 'Paris' },
          { value: 'lyon', label: 'Lyon' },
        ],
      },
      {
        value: 'de',
        label: 'Germany',
        children: [
          { value: 'berlin', label: 'Berlin' },
          { value: 'munich', label: 'Munich' },
        ],
      },
    ],
  },
  {
    value: 'north-america',
    label: 'North America',
    children: [
      {
        value: 'us',
        label: 'United States',
        children: [
          { value: 'new-york', label: 'New York' },
          { value: 'san-francisco', label: 'San Francisco' },
        ],
      },
      {
        value: 'ca',
        label: 'Canada',
        children: [
          { value: 'toronto', label: 'Toronto' },
          { value: 'vancouver', label: 'Vancouver' },
        ],
      },
    ],
  },
];
```


## Read only

Set `readOnly` to prevent opening the dropdown and changing the value:

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

function Demo() {
  const withColumns = useMatches({ base: false, sm: true });
  return (
    <Cascader
      withColumns={withColumns}
      readOnly
      label="Location"
      placeholder="Pick location"
      defaultValue={['asia', 'jp', 'tokyo']}
      data={data}
    />
  );
}
```


## Disabled

Set `disabled` to disable the input:

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

function Demo() {
  const withColumns = useMatches({ base: false, sm: true });
  return (
    <Cascader
      withColumns={withColumns}
      disabled
      label="Location"
      placeholder="Pick location"
      data={data}
    />
  );
}
```


## Error state

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

function Demo() {
  const withColumns = useMatches({ base: false, sm: true });
  return (
    <Cascader
      withColumns={withColumns}
      label="Location"
      placeholder="Pick location"
      error="Pick a valid location"
      data={data}
    />
  );
}
```


## Success state

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

function Demo() {
  return (
    <Cascader
      label="Location"
      placeholder="Pick location"
      defaultValue={['asia', 'jp', 'tokyo']}
      success="Looks good!"
      data={data}
    />
  );
}
```


## Loading state

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

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

function Demo() {
  return (
    <Cascader
      label="Location"
      placeholder="Pick location"
      loading
      data={data}
    />
  );
}
```


## Accessibility

Set the `label` prop or `aria-label` to make the input accessible for screen readers:

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


#### Props

**Cascader props**

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| allowDeselect | boolean | true | If set, the selected value can be deselected by selecting it again |
| changeOnSelect | boolean | false | If set, any intermediate option can be selected, not only leaf options |
| checkIconPosition | "left" \| "right" | 'right' | Position of the check icon relative to the option label |
| chevronColor | MantineColor | - | Controls the default chevron color |
| clearButtonProps | InputClearButtonProps | - | Props passed down to the clear button |
| clearSectionMode | ClearSectionMode | 'both' | Determines how the clear button and `rightSection` are rendered |
| clearable | boolean | false | If set, the clear button is displayed when a value is selected |
| closeOnSelect | boolean | - | Determines whether the dropdown should be closed when a value is selected, defaults to `!allowDeselect` |
| columnWidth | string \| number | - | Width of each column |
| comboboxProps | ComboboxProps | - | Props passed down to the underlying `Combobox` component |
| data | CascaderOption[] | required | Hierarchical options data |
| defaultDropdownOpened | boolean | - | Uncontrolled dropdown opened state |
| defaultSearchValue | string | - | Uncontrolled search value |
| defaultValue | string[] \| null | - | Uncontrolled selected path from root to node |
| description | React.ReactNode | - | Contents of `Input.Description` component. If not set, description is not displayed. |
| descriptionProps | InputDescriptionProps & DataAttributes & PlaceholderPolymorphicProps | - | Props passed down to the `Input.Description` component |
| disabled | boolean | - | Sets `disabled` attribute on the `input` element |
| dropdownOpened | boolean | - | Controlled dropdown opened state |
| error | React.ReactNode | - | Contents of `Input.Error` component. If not set, error is not displayed. |
| errorProps | InputErrorProps & DataAttributes & PlaceholderPolymorphicProps | - | Props passed down to the `Input.Error` component |
| expandTrigger | "hover" \| "click" | 'click' | Determines how the next column is opened |
| filter | (query: string, options: CascaderOption[]) => boolean | - | Custom search filter, matched against the full option path |
| formatValue | CascaderFormatValue | - | A function to format the selected path displayed in the input, should return a string |
| hiddenInputProps | React.ComponentProps<"input"> | - | Props passed down to the hidden input |
| inputContainer | (children: ReactNode) => ReactNode | (children) => children | Render function to wrap the input element. Useful for adding tooltips, popovers, or other wrappers around the input. |
| inputSize | string | - | HTML `size` attribute for the input element (number of visible characters) |
| inputWrapperOrder | ("input" \| "label" \| "description" \| "error")[] | ['label', 'description', 'input', 'error'] | Controls order and visibility of wrapper elements. Only elements included in this array will be rendered. |
| label | React.ReactNode | - | Contents of `Input.Label` component. If not set, label is not displayed. |
| labelProps | InputLabelProps & DataAttributes & PlaceholderPolymorphicProps | - | Props passed down to the `Input.Label` component |
| leftSection | React.ReactNode | - | Content section displayed on the left side of the input |
| leftSectionPointerEvents | React.CSSProperties["pointerEvents"] | 'none' | Sets `pointer-events` styles on the `leftSection` element. Use `'all'` when section contains interactive elements (buttons, links). |
| leftSectionProps | React.ComponentProps<"div"> | - | Props passed down to the `leftSection` element |
| leftSectionWidth | React.CSSProperties["width"] | - | Left section width, used to set `width` of the section and input `padding-left`, by default equals to the input height |
| loaderProps | LoaderProps | - | Props passed down to the `Loader` component displayed when `loading` prop is set |
| loading | boolean | false | Displays loading indicator in the left or right section |
| loadingPosition | "left" \| "right" | 'right' | Position of the loading indicator |
| maxDisplayedLevels | number | 3 | Maximum number of columns (levels) displayed next to each other, deeper levels replace earlier ones |
| maxDropdownHeight | string \| number | 260 | Max height of a column before it becomes scrollable |
| nextLevelsControlLabel | string | 'Show next levels' | `aria-label` and `title` of the control that reveals levels hidden after the visible ones by `maxDisplayedLevels` |
| nothingFoundMessage | React.ReactNode | - | Message displayed when there are no options or search results |
| onChange | (value: string[] \| null, options: CascaderOption[]) => void | - | Called when the selected path changes with the path and the resolved option chain |
| onClear | () => void | - | Called when the clear button is clicked |
| onDropdownClose | () => void | - | Called when the dropdown closes |
| onDropdownOpen | () => void | - | Called when the dropdown opens |
| onSearchChange | (value: string) => void | - | Called when the search value changes |
| openOnFocus | boolean | true | Opens the dropdown when the input is focused in `searchable` mode |
| pointer | boolean | false | Determines whether the input should use the theme cursor type. Use when input acts as a button-like trigger (e.g., `component="button"` for Select/DatePicker). |
| previousLevelsControlLabel | string | 'Show previous levels' | `aria-label` and `title` of the control that reveals levels hidden before the visible ones by `maxDisplayedLevels` |
| radius | MantineRadius \| number | theme.defaultRadius | Key of `theme.radius` or any valid CSS value to set `border-radius`, numbers are converted to rem |
| renderOption | (option: CascaderOption, level: number) => ReactNode | - | Custom rendering of an option in columns |
| renderSearchOption | (query: string, options: CascaderOption[]) => ReactNode | - | Custom rendering of a search result row |
| required | boolean | false | Adds required attribute to the input and a red asterisk on the right side of label |
| rightSection | React.ReactNode | - | Content section displayed on the right side of the input |
| rightSectionPointerEvents | React.CSSProperties["pointerEvents"] | 'none' | Sets `pointer-events` styles on the `rightSection` element. Use `'all'` when section contains interactive elements (buttons, links). |
| rightSectionProps | React.ComponentProps<"div"> | - | Props passed down to the `rightSection` element |
| rightSectionWidth | React.CSSProperties["width"] | - | Right section width, used to set `width` of the section and input `padding-right`, by default equals to the input height |
| safeAreaPolygon | boolean \| CascaderSafeAreaPolygonOptions | true | 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. |
| scrollAreaProps | ScrollAreaProps | - | Props passed down to the dropdown `ScrollArea` |
| searchValue | string | - | Controlled search value |
| searchable | boolean | false | If set, options can be searched by their flattened paths |
| separator | React.ReactNode | '/' | Path separator displayed in the input and search results |
| size | MantineSize | 'sm' | Controls input `height`, horizontal `padding`, and `font-size` |
| success | React.ReactNode | - | Contents of `Input.Success` component. If not set, success is not displayed. |
| successProps | InputSuccessProps & DataAttributes & PlaceholderPolymorphicProps | - | Props passed down to the `Input.Success` component |
| value | string[] \| null | - | Controlled selected path from root to node |
| virtualizer | ComponentType<ComboboxVirtualizerProps> | - | Component that virtualizes search results and the flat list shown when `withColumns` is false |
| withAsterisk | boolean | false | If set, the required asterisk is displayed next to the label. Overrides `required` prop. Does not add required attribute to the input. |
| withCheckIcon | boolean | true | If set, the check icon is displayed on the selected option |
| withColumns | boolean | true | 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) |
| withErrorStyles | boolean | true | Determines whether the input should have red border and red text color when the `error` prop is set |
| withSuccessStyles | boolean | true | Determines whether the input should have green border when the `success` prop is set |
| wrapperProps | WrapperProps | - | Props passed down to the root element |


#### Styles API

Cascader component supports Styles API. With Styles API, you can customize styles of any inner element. Follow the documentation to learn how to use CSS modules, CSS variables and inline styles to get full control over component styles.

**Cascader selectors**

| Selector | Static selector | Description |
|----------|----------------|-------------|
| wrapper | .mantine-Cascader-wrapper | Root element of the Input |
| input | .mantine-Cascader-input | Input element |
| section | .mantine-Cascader-section | Left and right sections |
| bottomSection | .mantine-Cascader-bottomSection | Bottom section element, rendered inside the input border at the bottom |
| root | .mantine-Cascader-root | Root element |
| childrenWrapper | .mantine-Cascader-childrenWrapper | Container of `children`, rendered only when `withBlockChildren` prop is set |
| label | .mantine-Cascader-label | Label element |
| required | .mantine-Cascader-required | Required asterisk element, rendered inside label |
| description | .mantine-Cascader-description | Description element |
| error | .mantine-Cascader-error | Error element |
| success | .mantine-Cascader-success | Success element |
| columnsList | .mantine-Cascader-columnsList | Wrapper of all cascading columns in the dropdown |
| columnsOverflow | .mantine-Cascader-columnsOverflow | Control displayed to reveal levels hidden by `maxDisplayedLevels` |
| column | .mantine-Cascader-column | Single cascading column |
| columnScroll | .mantine-Cascader-columnScroll | Scrollable options area of a column |
| columnOption | .mantine-Cascader-columnOption | Option control inside a column |
| columnOptionLabel | .mantine-Cascader-columnOptionLabel | Label of the column option |
| columnOptionIcon | .mantine-Cascader-columnOptionIcon | Expand chevron of the column option |
| columnOptionCheck | .mantine-Cascader-columnOptionCheck | Check icon displayed on the selected option |
| columnEmpty | .mantine-Cascader-columnEmpty | Empty state of a column |
| flatOption | .mantine-Cascader-flatOption | Option content in the flat list (search results / `withColumns={false}`) |

**Cascader data attributes**

| Selector | Attribute | Condition | Value |
|----------|-----------|-----------|-------|
| columnOption | data-current | Option is the keyboard-current option in the column that is being navigated | - |
| columnOption | data-in-path | Option is highlighted in one of the previous (ancestor) columns | - |
| columnOption | data-selected | Option is the selected value | - |
| columnOption | data-disabled | Option is disabled | - |
