@mantine/core/lib/components/Cascader/Cascader.d.ts

React components library focused on usability, accessibility and developer experience

import type { SafePolygonOptions } from '@floating-ui/react';
import { BoxProps, ElementProps, Factory, MantineColor, StylesApiProps } from '../../core';
import { ComboboxLikeStylesNames } from '../Combobox';
import { __BaseInputProps, __InputStylesNames, ClearSectionMode, InputClearButtonProps, InputVariant } from '../Input';
import { ScrollAreaProps } from '../ScrollArea';
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 declare const Cascader: import("../..").MantineComponent<{
    props: CascaderProps;
    ref: HTMLInputElement;
    stylesNames: CascaderStylesNames;
    variant: InputVariant;
}>;