Cascader

Cascade selection box.

When To Use#

  • When you need to select from a set of associated data set. Such as province/city/district, company level, things classification.
  • When selecting from a large data set, with multi-stage classification separated for easy selection.
  • Chooses cascade items in one float layer for 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...
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 return 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 disabled selectbooleanfalse
[nzExpandIcon]Customize the current item expand iconstring|TemplateRef<void>-
[nzExpandTrigger]expand current item when click or hover, 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. If setting ngModel with an array value and nzOptions is not setting, lazy load will be call immediately(option: any, index?: index) => PromiseLike<any>-
[nzMenuClassName]additional className of popup overlaystring-
[nzMenuStyle]additional css style of popup overlayobject-
[nzNotFoundContent]Specify content to show when no result matches.string|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'
[nzSuffixIcon]The custom suffix iconstring|TemplateRef<void>-
[nzValueProperty]the 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 is like:

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