Cascader

Cascade selection box.

When To Use#

  • When you need to select from a set of a hierarchical structure. Such as province/city/district, company level, and classification.
  • When selecting from a large data set, with multi-stage classification separated for easy selection.
  • Chooses cascade items in one float layer for a better user experience.
import { NzCascaderModule } from 'ng-zorro-antd/cascader';

Examples

Please select
  Change Options

Cascade selection box for selecting province/city/district.

expand codeexpand code
Loading...
Unselect

Separate trigger button and result.

expand codeexpand code
Loading...
Please select

Disable option by specifying the disabled property in options.

expand codeexpand code
Loading...
Please select
Please select
Please select

Cascade selection box of different sizes.

expand codeexpand code
Loading...
Please select

Reset control value by Ng Reactive Form.

expand codeexpand code
Loading...
Please select

Allow select option only on nzChangeOn return true.

expand codeexpand code
Loading...
Zhejiang / Hangzhou / West Lake

Specifies default value by an array, but nzOptions is null/empty, data are loaded by nzLoadData function.

expand codeexpand code
Loading...
Please select

Custom field names.

expand codeexpand code
Loading...
Please select
Please select

Add status to Cascader with nzStatus, which could be error or warning.

expand codeexpand code
Loading...
Zhejiang / Hangzhou / West Lake

Specifies default value by an array.

expand codeexpand code
Loading...
Please select

Hover to expand sub menu, click to select option.

expand codeexpand code
Loading...
Please select

Allow only select parent options.

expand codeexpand code
Loading...
Please select

For instance, add an external link after the selected value.

expand codeexpand code
Loading...
Please select

Load options lazily with nzLoadData.

expand codeexpand code
Loading...

Show Cascade selection box in a modal dialog.

expand codeexpand code
Loading...
Please select

Show menu on mouse enter and hide on mouse leave.

expand codeexpand code
Loading...
Zhejiang / Hangzhou / West Lake

Specifies default value by an array, and setting nzOptions in a asynchronous way.

expand codeexpand code
Loading...
Please select

Custom cascader option template.

expand codeexpand code
Loading...

API#

<nz-cascader [nzOptions]="options" [(ngModel)]="values"></nz-cascader>

nz-cascader#

PropertyDescriptionTypeDefaultGlobal Config
[ngModel]selected valueany[]-
[nzAllowClear]whether allow clearbooleantrue
[nzAutoFocus]whether auto focus the input boxbooleanfalse
[nzBackdrop]whether or not the overlay should attach a backdropbooleanfalse
[nzChangeOn]change value on each selection if this function returns true(option: any, index: number) => boolean-
[nzChangeOnSelect]change value on each selection if set to true, see above demo for detailsbooleanfalse
[nzColumnClassName]additional className of column in the popup overlaystring-
[nzDisabled]whether select should be disabledbooleanfalse
[nzExpandIcon]customize the current item expand iconstring|TemplateRef<void>-
[nzExpandTrigger]expand current item when clicked or hovered, one of 'click' 'hover''click'|'hover''click'
[nzLabelProperty]the label property name of optionsstring'label'
[nzLabelRender]render template of displaying selected optionsTemplateRef<any>-
[nzLoadData]to load option lazily. Lazy load will be called immediately if the setting is ngModel with an array value and nzOptions is not set(option: any, index?: index) => PromiseLike<any> | Observable<any>-
[nzMenuClassName]additional className of popup overlaystring-
[nzMenuStyle]additional css style of popup overlayobject-
[nzNotFoundContent]specify content to show when no result matchesstring|TemplateRef<void>-
[nzOptionRender]render template of cascader optionsTemplateRef<{ $implicit: NzCascaderOption, index: number }>
[nzOptions]data options of cascadeobject[]-
[nzPlaceHolder]input placeholderstring'Please select'
[nzShowArrow]whether show arrowbooleantrue
[nzShowInput]whether show inputbooleantrue
[nzShowSearch]whether support search. Cannot be used with [nzLoadData] at the same timeboolean|NzShowSearchOptionsfalse
[nzSize]input size, one of largedefaultsmall'large'|'small'|'default''default'
[nzStatus]set validation status'error' | 'warning'-
[nzSuffixIcon]custom suffix iconstring|TemplateRef<void>-
[nzValueProperty]value property name of optionsstring'value'
(ngModelChange)emit on values changeEventEmitter<any[]>-
(nzClear)emit on clear valuesEventEmitter<void>-
(nzVisibleChange)emit on popup menu visible or hideEventEmitter<boolean>-
(nzSelectionChange)emit on values changeEventEmitter<NzCascaderOption[]>-

When nzShowSearch is an object it should implements NzShowSearchOptions

ParamsExplanationTypeDefault
filterOptional. Be aware that all non-leaf CascaderOptions would be filtered(inputValue: string, path: NzCascaderOption[]): boolean-
sorterOptional(a: NzCascaderOption[], b: NzCascaderOption[], inputValue: string): number-

The default filter looks as follows:

const defaultFilter: NzCascaderFilter = (i, p) => {
  return p.some(o => {
    const label = o.label;
    return !!label && label.indexOf(i) !== -1;
  });
};

For example, if you would like to ignore lower or upper case, you could use a filter function like this:

const filter: NzCascaderFilter = (i, p) => {
  return p.some(o => {
    const label = o.label;
    return !!label && label.toLowerCase().indexOf(i.toLowerCase()) !== -1;
  });
};

Methods#

NameDescription
blur()remove focus
focus()get focus
closeMenu()hide the menu

FAQ#

Q: An error is thrown when nzLoadData is used.#

When you pass a function to nzLoadData, the function becomes a NzCascaderComponent property. When the component calls the nzLoadData function, this is bound to nothing. You have to pass an arrow function or use Function.bind to bind this to the parent component; see example.