Select

Select component to select value from options.

When To Use#

  • A dropdown menu for displaying choices - an elegant alternative to the native <select> element.
  • Utilizing Radio is recommended when there are fewer total options (less than 5).

Import this Component Individually#

You can get more detail here.

import { NzSelectModule } from 'ng-zorro-antd/select';

Examples

Lucy
Lucy
Lucy

Basic Usage.

expand codeexpand code
import { Component } from '@angular/core';

@Component({
  selector: 'nz-demo-select-basic',
  template: `
    <div>
      <nz-select [(ngModel)]="selectedValue" nzAllowClear nzPlaceHolder="Choose">
        <nz-option nzValue="jack" nzLabel="Jack"></nz-option>
        <nz-option nzValue="lucy" nzLabel="Lucy"></nz-option>
        <nz-option nzValue="disabled" nzLabel="Disabled" nzDisabled></nz-option>
      </nz-select>
      <nz-select [ngModel]="'lucy'" nzDisabled>
        <nz-option nzValue="lucy" nzLabel="Lucy"></nz-option>
      </nz-select>
      <nz-select [ngModel]="'lucy'" nzLoading>
        <nz-option nzValue="lucy" nzLabel="Lucy"></nz-option>
      </nz-select>
    </div>
  `,
  styles: [
    `
      nz-select {
        margin-right: 8px;
        width: 120px;
      }
    `
  ]
})
export class NzDemoSelectBasicComponent {
  selectedValue = 'lucy';
}
  • a10
  • c12

Multiple selection, selecting from existing items, max 3 option will display at the same time by nzMaxTagCount.

expand codeexpand code
import { Component, OnInit } from '@angular/core';

@Component({
  selector: 'nz-demo-select-multiple',
  template: `
    <nz-select
      [nzMaxTagCount]="3"
      [nzMaxTagPlaceholder]="tagPlaceHolder"
      nzMode="multiple"
      nzPlaceHolder="Please select"
      [(ngModel)]="listOfSelectedValue"
    >
      <nz-option *ngFor="let option of listOfOption" [nzLabel]="option.label" [nzValue]="option.value"></nz-option>
    </nz-select>
    <ng-template #tagPlaceHolder let-selectedList> and {{ selectedList.length }} more selected </ng-template>
  `,
  styles: [
    `
      nz-select {
        width: 100%;
      }
    `
  ]
})
export class NzDemoSelectMultipleComponent implements OnInit {
  listOfOption: Array<{ label: string; value: string }> = [];
  listOfSelectedValue = ['a10', 'c12'];

  ngOnInit(): void {
    const children: Array<{ label: string; value: string }> = [];
    for (let i = 10; i < 36; i++) {
      children.push({ label: i.toString(36) + i, value: i.toString(36) + i });
    }
    this.listOfOption = children;
  }
}
Tag Mode

Select with tags, transform input to tag (scroll the menu)

expand codeexpand code
import { Component, OnInit } from '@angular/core';

@Component({
  selector: 'nz-demo-select-tags',
  template: `
    <nz-select nzMode="tags" nzPlaceHolder="Tag Mode" [(ngModel)]="listOfTagOptions">
      <nz-option *ngFor="let option of listOfOption" [nzLabel]="option.label" [nzValue]="option.value"></nz-option>
    </nz-select>
  `,
  styles: [
    `
      nz-select {
        width: 100%;
      }
    `
  ]
})
export class NzDemoSelectTagsComponent implements OnInit {
  listOfOption: Array<{ label: string; value: string }> = [];
  listOfTagOptions = [];

  ngOnInit(): void {
    const children: Array<{ label: string; value: string }> = [];
    for (let i = 10; i < 36; i++) {
      children.push({ label: i.toString(36) + i, value: i.toString(36) + i });
    }
    this.listOfOption = children;
  }
}
Zhejiang
Hangzhou

Coordinating the selection of provinces and cities is a common use case and demonstrates how selection can be coordinated.

Using the Cascader component is strongly recommended instead as it is more flexible and capable.

expand codeexpand code
import { Component } from '@angular/core';

@Component({
  selector: 'nz-demo-select-coordinate',
  template: `
    <div>
      <nz-select [(ngModel)]="selectedProvince" (ngModelChange)="provinceChange($event)">
        <nz-option *ngFor="let p of provinceData" [nzValue]="p" [nzLabel]="p"></nz-option>
      </nz-select>
      <nz-select [(ngModel)]="selectedCity">
        <nz-option *ngFor="let c of cityData[selectedProvince]" [nzValue]="c" [nzLabel]="c"></nz-option>
      </nz-select>
    </div>
  `,
  styles: [
    `
      nz-select {
        margin-right: 8px;
        width: 120px;
      }
    `
  ]
})
export class NzDemoSelectCoordinateComponent {
  selectedProvince = 'Zhejiang';
  selectedCity = 'Hangzhou';
  provinceData = ['Zhejiang', 'Jiangsu'];
  cityData: { [place: string]: string[] } = {
    Zhejiang: ['Hangzhou', 'Ningbo', 'Wenzhou'],
    Jiangsu: ['Nanjing', 'Suzhou', 'Zhenjiang']
  };

  provinceChange(value: string): void {
    this.selectedCity = this.cityData[value][0];
  }
}

The selected option's age is 22


Jack

The value of ngModel comes from the nzValue of nz-option, when the nzValue of nz-option is an object, the ngModel will be an object too, the usage of compareWith is the same as SelectControlValueAccessor.

expand codeexpand code
import { Component } from '@angular/core';

@Component({
  selector: 'nz-demo-select-label-in-value',
  template: `
    <p>The selected option's age is {{ selectedValue?.age }}</p>
    <br />
    <nz-select
      [(ngModel)]="selectedValue"
      [compareWith]="compareFn"
      (ngModelChange)="log($event)"
      nzAllowClear
      nzPlaceHolder="Choose"
    >
      <nz-option *ngFor="let option of optionList" [nzValue]="option" [nzLabel]="option.label"></nz-option>
    </nz-select>
  `,
  styles: [
    `
      nz-select {
        width: 120px;
      }
    `
  ]
})
export class NzDemoSelectLabelInValueComponent {
  optionList = [{ label: 'Lucy', value: 'lucy', age: 20 }, { label: 'Jack', value: 'jack', age: 22 }];
  selectedValue = { label: 'Jack', value: 'jack', age: 22 };
  // tslint:disable-next-line:no-any
  compareFn = (o1: any, o2: any) => (o1 && o2 ? o1.value === o2.value : o1 === o2);

  log(value: { label: string; value: string; age: number }): void {
    console.log(value);
  }
}
Select users

A complete multiple select sample with remote search, debounce fetch, ajax callback order flow, and loading state.

expand codeexpand code
import { HttpClient } from '@angular/common/http';
import { Component, OnInit } from '@angular/core';
import { BehaviorSubject, Observable } from 'rxjs';
import { debounceTime, map, switchMap } from 'rxjs/operators';

@Component({
  selector: 'nz-demo-select-select-users',
  template: `
    <nz-select
      nzMode="multiple"
      nzPlaceHolder="Select users"
      nzAllowClear
      nzShowSearch
      nzServerSearch
      [(ngModel)]="selectedUser"
      (nzOnSearch)="onSearch($event)"
    >
      <ng-container *ngFor="let o of optionList">
        <nz-option *ngIf="!isLoading" [nzValue]="o" [nzLabel]="o"></nz-option>
      </ng-container>
      <nz-option *ngIf="isLoading" nzDisabled nzCustomContent>
        <i nz-icon nzType="loading" class="loading-icon"></i> Loading Data...
      </nz-option>
    </nz-select>
  `,
  styles: [
    `
      nz-select {
        width: 100%;
      }

      .loading-icon {
        margin-right: 8px;
      }
    `
  ]
})
export class NzDemoSelectSelectUsersComponent implements OnInit {
  randomUserUrl = 'https://api.randomuser.me/?results=5';
  searchChange$ = new BehaviorSubject('');
  optionList: string[] = [];
  selectedUser: string;
  isLoading = false;

  onSearch(value: string): void {
    this.isLoading = true;
    this.searchChange$.next(value);
  }

  constructor(private http: HttpClient) {}

  ngOnInit(): void {
    // tslint:disable:no-any
    const getRandomNameList = (name: string) =>
      this.http
        .get(`${this.randomUserUrl}`)
        .pipe(map((res: any) => res.results))
        .pipe(
          map((list: any) => {
            return list.map((item: any) => `${item.name.first} ${name}`);
          })
        );
    const optionList$: Observable<string[]> = this.searchChange$
      .asObservable()
      .pipe(debounceTime(500))
      .pipe(switchMap(getRandomNameList));
    optionList$.subscribe(data => {
      this.optionList = data;
      this.isLoading = false;
    });
  }
}
Inserted are removed

Hide already selected options in the dropdown via nzHide.

expand codeexpand code
import { Component } from '@angular/core';

@Component({
  selector: 'nz-demo-select-hide-selected',
  template: `
    <nz-select nzMode="multiple" nzPlaceHolder="Inserted are removed" [(ngModel)]="listOfSelectedValue">
      <nz-option
        *ngFor="let option of listOfOption"
        [nzLabel]="option"
        [nzValue]="option"
        [nzHide]="!isNotSelected(option)"
      ></nz-option>
    </nz-select>
  `,
  styles: [
    `
      nz-select {
        width: 100%;
      }
    `
  ]
})
export class NzDemoSelectHideSelectedComponent {
  listOfOption = ['Apples', 'Nails', 'Bananas', 'Helicopters'];
  listOfSelectedValue: string[] = [];

  isNotSelected(value: string): boolean {
    return this.listOfSelectedValue.indexOf(value) === -1;
  }
}
Select users

Load data on scroll.

expand codeexpand code
import { HttpClient } from '@angular/common/http';
import { Component, OnInit } from '@angular/core';
import { Observable } from 'rxjs';
import { map } from 'rxjs/operators';

@Component({
  selector: 'nz-demo-select-scroll-load',
  template: `
    <nz-select [(ngModel)]="selectedUser" (nzScrollToBottom)="loadMore()" nzPlaceHolder="Select users" nzAllowClear>
      <nz-option *ngFor="let o of optionList" [nzValue]="o" [nzLabel]="o"></nz-option>
      <nz-option *ngIf="isLoading" nzDisabled nzCustomContent>
        <i nz-icon nzType="loading" class="loading-icon"></i> Loading Data...
      </nz-option>
    </nz-select>
  `,
  styles: [
    `
      nz-select {
        width: 100%;
      }

      .loading-icon {
        margin-right: 8px;
      }
    `
  ]
})
export class NzDemoSelectScrollLoadComponent implements OnInit {
  randomUserUrl = 'https://api.randomuser.me/?results=10';
  optionList: string[] = [];
  selectedUser = null;
  isLoading = false;
  // tslint:disable:no-any
  getRandomNameList: Observable<string[]> = this.http
    .get(`${this.randomUserUrl}`)
    .pipe(map((res: any) => res.results))
    .pipe(
      map((list: any) => {
        return list.map((item: any) => `${item.name.first}`);
      })
    );

  loadMore(): void {
    this.isLoading = true;
    this.getRandomNameList.subscribe(data => {
      this.isLoading = false;
      this.optionList = [...this.optionList, ...data];
    });
  }

  constructor(private http: HttpClient) {}

  ngOnInit(): void {
    this.loadMore();
  }
}
  • Default 01
  • Default 02


Default Value

Display a default value that not in the option list with nzHide in nz-option

expand codeexpand code
import { Component } from '@angular/core';

@Component({
  selector: 'nz-demo-select-default-value',
  template: `
    <nz-select nzMode="multiple" nzPlaceHolder="Inserted are removed" [(ngModel)]="listOfSelectedValue">
      <nz-option *ngFor="let option of listOfOption" [nzLabel]="option" [nzValue]="option"></nz-option>
      <nz-option *ngFor="let option of defaultOption" [nzLabel]="option" [nzValue]="option" nzHide></nz-option>
    </nz-select>
    <br />
    <br />
    <nz-select [(ngModel)]="selectedValue">
      <nz-option *ngFor="let option of listOfOption" [nzLabel]="option" [nzValue]="option"></nz-option>
      <nz-option nzLabel="Default Value" nzValue="Default" nzHide></nz-option>
    </nz-select>
  `,
  styles: [
    `
      nz-select {
        width: 100%;
      }
    `
  ]
})
export class NzDemoSelectDefaultValueComponent {
  listOfOption = ['Option 01', 'Option 02'];
  listOfSelectedValue = ['Default 01', 'Default 02'];
  defaultOption = [...this.listOfSelectedValue];

  selectedValue = 'Default';
}


a10


a10


  • a10
  • c12


  • a10
  • c12
  • tag

The height of the input field for the select defaults to 32px. If nzSize is set to large, the height will be 40px, and if set to small, 24px.

expand codeexpand code
import { Component, OnInit } from '@angular/core';

@Component({
  selector: 'nz-demo-select-size',
  template: `
    <nz-radio-group [(ngModel)]="size">
      <label nz-radio-button nzValue="large"><span>Large</span></label>
      <label nz-radio-button nzValue="default"><span>Default</span></label>
      <label nz-radio-button nzValue="small"><span>Small</span></label>
    </nz-radio-group>
    <br /><br />
    <nz-select [(ngModel)]="singleValue" [nzSize]="size">
      <nz-option *ngFor="let option of listOfOption" [nzLabel]="option.label" [nzValue]="option.value"></nz-option>
    </nz-select>
    <br /><br />
    <nz-select [(ngModel)]="singleValue" [nzSize]="size" nzShowSearch>
      <nz-option *ngFor="let option of listOfOption" [nzLabel]="option.label" [nzValue]="option.value"></nz-option>
    </nz-select>
    <br /><br />
    <nz-select [(ngModel)]="multipleValue" [nzSize]="size" nzMode="multiple" nzPlaceHolder="Please select">
      <nz-option *ngFor="let option of listOfOption" [nzLabel]="option.label" [nzValue]="option.value"></nz-option>
    </nz-select>
    <br /><br />
    <nz-select [(ngModel)]="tagValue" [nzSize]="size" nzMode="tags" nzPlaceHolder="Please select">
      <nz-option *ngFor="let option of listOfOption" [nzLabel]="option.label" [nzValue]="option.value"></nz-option>
    </nz-select>
  `,
  styles: [
    `
      nz-select {
        width: 100%;
      }
    `
  ]
})
export class NzDemoSelectSizeComponent implements OnInit {
  listOfOption: Array<{ label: string; value: string }> = [];
  size = 'default';
  singleValue = 'a10';
  multipleValue = ['a10', 'c12'];
  tagValue = ['a10', 'c12', 'tag'];

  ngOnInit(): void {
    const children: Array<{ label: string; value: string }> = [];
    for (let i = 10; i < 36; i++) {
      children.push({ label: i.toString(36) + i, value: i.toString(36) + i });
    }
    this.listOfOption = children;
  }
}
Lucy

Using nz-option-group to group the options.

expand codeexpand code
import { Component } from '@angular/core';

@Component({
  selector: 'nz-demo-select-optgroup',
  template: `
    <nz-select [(ngModel)]="selectedValue" nzAllowClear nzPlaceHolder="Choose">
      <nz-option-group nzLabel="Manager">
        <nz-option nzValue="jack" nzLabel="Jack"></nz-option>
        <nz-option nzValue="lucy" nzLabel="Lucy"></nz-option>
      </nz-option-group>
      <nz-option-group nzLabel="Engineer">
        <nz-option nzValue="Tom" nzLabel="tom"></nz-option>
      </nz-option-group>
    </nz-select>
  `,
  styles: [
    `
      nz-select {
        width: 120px;
      }
    `
  ]
})
export class NzDemoSelectOptgroupComponent {
  selectedValue = 'lucy';
}
automatic tokenization

Try to copy Lucy,Jack to the input. Only available in tags and multiple mode.

expand codeexpand code
import { Component, OnInit } from '@angular/core';

@Component({
  selector: 'nz-demo-select-automatic-tokenization',
  template: `
    <nz-select
      [(ngModel)]="listOfTagOptions"
      nzMode="tags"
      [nzTokenSeparators]="[',']"
      nzPlaceHolder="automatic tokenization"
    >
      <nz-option *ngFor="let option of listOfOption" [nzLabel]="option.label" [nzValue]="option.value"></nz-option>
    </nz-select>
  `,
  styles: [
    `
      nz-select {
        width: 100%;
      }
    `
  ]
})
export class NzDemoSelectAutomaticTokenizationComponent implements OnInit {
  listOfOption: Array<{ label: string; value: string }> = [];
  listOfTagOptions = [];

  ngOnInit(): void {
    const children: Array<{ label: string; value: string }> = [];
    for (let i = 10; i < 36; i++) {
      children.push({ label: i.toString(36) + i, value: i.toString(36) + i });
    }
    this.listOfOption = children;
  }
}
Lucy

Customize the dropdown menu via nzDropdownRender.

expand codeexpand code
import { Component } from '@angular/core';

@Component({
  selector: 'nz-demo-select-custom-dropdown-menu',
  template: `
    <nz-select nzShowSearch nzAllowClear [ngModel]="'lucy'" [nzDropdownRender]="render">
      <nz-option nzValue="jack" nzLabel="Jack"></nz-option>
      <nz-option nzValue="lucy" nzLabel="Lucy"></nz-option>
    </nz-select>
    <ng-template #render>
      <nz-divider></nz-divider>
      <div class="add-item"><i nz-icon nzType="plus"></i> Add item</div>
    </ng-template>
  `,
  styles: [
    `
      nz-select {
        width: 120px;
      }

      nz-divider {
        margin: 4px 0;
      }

      .add-item {
        padding: 8px;
        cursor: pointer;
      }
    `
  ]
})
export class NzDemoSelectCustomDropdownMenuComponent {}
Select OS

Custom the content of nz-option via nzCustomContent.

expand codeexpand code
import { Component } from '@angular/core';

@Component({
  selector: 'nz-demo-select-custom-content',
  template: `
    <nz-select nzShowSearch nzAllowClear nzPlaceHolder="Select OS" [(ngModel)]="selectedOS">
      <nz-option nzCustomContent nzLabel="Windows" nzValue="windows"
        ><i nz-icon nzType="windows"></i> Windows</nz-option
      >
      <nz-option nzCustomContent nzLabel="Mac" nzValue="mac"><i nz-icon nzType="apple"></i> Mac</nz-option>
      <nz-option nzCustomContent nzLabel="Android" nzValue="android"
        ><i nz-icon nzType="android"></i> Android
      </nz-option>
    </nz-select>
  `,
  styles: [
    `
      nz-select {
        width: 200px;
      }
    `
  ]
})
export class NzDemoSelectCustomContentComponent {
  selectedOS = null;
}
Select OS

Custom the content of nz-select via nzCustomTemplate.

expand codeexpand code
import { Component } from '@angular/core';

@Component({
  selector: 'nz-demo-select-custom-template',
  template: `
    <nz-select nzAllowClear nzPlaceHolder="Select OS" [(ngModel)]="selectedOS" [nzCustomTemplate]="custom">
      <nz-option nzCustomContent nzLabel="Windows" nzValue="windows"
        ><i nz-icon nzType="windows"></i> Windows
      </nz-option>
      <nz-option nzCustomContent nzLabel="Mac" nzValue="mac"><i nz-icon nzType="apple"></i> Mac</nz-option>
      <nz-option nzCustomContent nzLabel="Android" nzValue="android"
        ><i nz-icon nzType="android"></i> Android
      </nz-option>
    </nz-select>
    <ng-template #custom let-selected>
      <span>Label: {{ selected.nzLabel }} Value: {{ selected.nzValue }}</span>
    </ng-template>
  `,
  styles: [
    `
      nz-select {
        width: 200px;
      }
    `
  ]
})
export class NzDemoSelectCustomTemplateComponent {
  selectedOS = null;
}

API#

<nz-select>
  <nz-option nzValue="lucy" nzLabel="Lucy"></nz-option>
</nz-select>

nz-select#

PropertyDescriptionTypeDefault
[ngModel]Current selected nz-option value, double binding.any | any[]-
[compareWith]Same as SelectControlValueAccessor(o1: any, o2: any) => boolean(o1: any, o2: any) => o1===o2
[nzAutoClearSearchValue]Whether the current search will be cleared on selecting an item. Only applies when mode is set to multiple or tags.booleantrue
[nzAllowClear]Show clear button.booleanfalse
[nzOpen]dropdown expand state, double bindingbooleanfalse
[nzAutoFocus]Get focus by defaultbooleanfalse
[nzDisabled]Whether disabled selectbooleanfalse
[nzDropdownClassName]className of dropdown menustring-
[nzDropdownMatchSelectWidth]Whether dropdown's with is same with select.booleantrue
[nzDropdownStyle]style of dropdown menuobject-
[nzCustomTemplate]The custom template of selectTemplateRef<{ $implicit: NzOptionComponent }>-
[nzServerSearch]nz-option will not be filtered when set to truebooleanfalse
[nzFilterOption]Filter options against it. The function will receive two arguments, inputValue and option, if the function returns true, the option will be included in the filtered set; Otherwise, it will be excluded.(input?: string, option?: NzOptionComponent) => boolean;-
[nzMaxMultipleCount]Max selected option can be selectednumberInfinity
[nzMode]Set mode of Select'multiple' | 'tags' | 'default''default'
[nzNotFoundContent]Specify content to show when no result matches..string | TemplateRef<void>'Not Found'
[nzPlaceHolder]Placeholder of selectstring-
[nzShowArrow]Whether to show the drop-down arrowbooleantrue
[nzShowSearch]Whether show search input in single mode.booleanfalse
[nzSize]Size of Select input'large' | 'small' | 'default''default'
[nzSuffixIcon]The custom suffix iconTemplateRef<void>-
[nzRemoveIcon]The custom remove iconTemplateRef<void>-
[nzClearIcon]The custom clear iconTemplateRef<void>-
[nzMenuItemSelectedIcon]The custom menuItemSelected iconTemplateRef<void>-
[nzTokenSeparators]Separator used to tokenize on tag/multiple modestring[][]
[nzLoading]indicate loading statebooleanfalse
[nzMaxTagCount]Max tag count to shownumber-
[nzMaxTagPlaceholder]Placeholder for not showing tagsTemplateRef<{ $implicit: any[] }>-
(ngModelChange)Current selected nz-option value change callback.EventEmitter<any[]>-
(nzOpenChange)dropdown expand change callbackEventEmitter<boolean>false
(nzScrollToBottom)Called when dropdown scrolls to bottomEventEmitter<void>-
(nzOnSearch)Callback function that is fired when input changed.EventEmitter<string>-
(nzFocus)focus callbackEventEmitter<void>-
(nzBlur)blur callbackEventEmitter<void>-

nz-option#

PropertyDescriptionTypeDefault
[nzDisabled]Disable this optionbooleanfalse
[nzLabel]The text show in nz-select and dropdown menustring-
[nzValue]The value passed to ngModel of nz-selectany-
[nzHide]Whether hide the option in the option listbooleanfalse
[nzCustomContent]Whether custom nz-option content in drodown menu, the ng-content in nz-option will relace nzLabel when it was set to truebooleanfalse

nz-option-group#

PropertyDescriptionTypeDefault
[nzLabel]Group labelstring | TemplateRef<void>-

Methods#

nz-select#

NameDescription
blur()Remove focus
focus()Get focus