Select

ion-select

Improve this doc

The ion-select component is similar to an HTML <select> element, however, Ionic's select component makes it easier for users to sort through and select the preferred option or options. When users tap the select component, a dialog will appear with all of the options in a large, easy to select list for users.

The select component takes child ion-option components. If ion-option is not given a value attribute then it will use its text as the value.

If ngModel is bound to ion-select, the selected value will be based on the bound value of the model. Otherwise, the selected attribute can be used on ion-option components.

Interfaces

By default, the ion-select uses the AlertController API to open up the overlay of options in an alert. The interface can be changed to use the ActionSheetController API or PopoverController API by passing action-sheet or popover, respectively, to the interface property. Read on to the other sections for the limitations of the different interfaces.

Single Value: Radio Buttons

The standard ion-select component allows the user to select only one option. When selecting only one option the alert interface presents users with a radio button styled list of options. The action sheet interface can only be used with a single value select. If the number of options exceed 6, it will use the alert interface even if action-sheet is passed. The ion-select component's value receives the value of the selected option's value.

<ion-item>
  <ion-label>Gender</ion-label>
  <ion-select [(ngModel)]="gender">
    <ion-option value="f">Female</ion-option>
    <ion-option value="m">Male</ion-option>
  </ion-select>
</ion-item>

Multiple Value: Checkboxes

By adding the multiple="true" attribute to ion-select, users are able to select multiple options. When multiple options can be selected, the alert overlay presents users with a checkbox styled list of options. The ion-select multiple="true" component's value receives an array of all the selected option values. In the example below, because each option is not given a value, then it'll use its text as the value instead.

Note: the action-sheet and popover interfaces will not work with a multi-value select.

<ion-item>
  <ion-label>Toppings</ion-label>
  <ion-select [(ngModel)]="toppings" multiple="true">
    <ion-option>Bacon</ion-option>
    <ion-option>Black Olives</ion-option>
    <ion-option>Extra Cheese</ion-option>
    <ion-option>Mushrooms</ion-option>
    <ion-option>Pepperoni</ion-option>
    <ion-option>Sausage</ion-option>
  </ion-select>
</ion-item>

Select Buttons

By default, the two buttons read Cancel and OK. Each button's text can be customized using the cancelText and okText attributes:

<ion-select okText="Okay" cancelText="Dismiss">
  ...
</ion-select>

The action-sheet and popover interfaces do not have an OK button, clicking on any of the options will automatically close the overlay and select that value.

Select Options

Since ion-select uses the Alert, Action Sheet and Popover interfaces, options can be passed to these components through the selectOptions property. This can be used to pass a custom title, subtitle, css class, and more. See the AlertController API docs, ActionSheetController API docs, and PopoverController API docs for the properties that each interface accepts.

For example, to change the mode of the overlay, pass it into selectOptions.

<ion-select [selectOptions]="selectOptions">
  ...
</ion-select>

this.selectOptions = {
  title: 'Pizza Toppings',
  subTitle: 'Select your toppings',
  mode: 'md'
};

Object Value References

When using objects for select values, it is possible for the identities of these objects to change if they are coming from a server or database, while the selected value's identity remains the same. For example, this can occur when an existing record with the desired object value is loaded into the select, but the newly retrieved select options now have different identities. This will result in the select appearing to have no value at all, even though the original selection in still intact.

Using the compareWith Input is the solution to this problem

<ion-item>
  <ion-label>Employee</ion-label>
  <ion-select [(ngModel)]="employee" [compareWith]="compareFn">
    <ion-option *ngFor="let employee of employees" [value]="employee"></ion-option>
  </ion-select>
</ion-item>

compareFn(e1: Employee, e2: Employee): boolean {
  return e1 && e2 ? e1.id === e2.id : e1 === e2;
}

Instance Members

close()

Close the select interface.

config

deepLinker

open()

Open the select interface.

options

Input Properties

Output Events

Sass Variables