Need help upgrading to Ionic Framework 4.0? Get assistance with our Enterprise Migration Services EXPLORE NOW

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

Attr Type Details
cancelText string

The text to display on the cancel button. Default: Cancel.

compareWith Function

The function that will be called to compare object values

interface string

The interface the select should use: action-sheet, popover or alert. Default: alert.

multiple boolean

If true, the element can accept multiple values.

okText string

The text to display on the ok button. Default: OK.

placeholder string

The text to display when the select is empty.

selectOptions any

Any additional options that the alert or action-sheet interface can take. See the AlertController API docs and the ActionSheetController API docs for the create options for each interface.

selectedText string

The text to display instead of the selected option's value.

Output Events

Attr Details
ionCancel

Emitted when the selection was cancelled.

Sass Variables

Property Default Description
$select-popover-list-margin-top -1px

Margin top of the select popover list

$select-popover-list-margin-end $select-popover-list-margin-right

Margin end of the select popover list

$select-popover-list-margin-bottom -1px

Margin bottom of the select popover list

$select-popover-list-margin-start $select-popover-list-margin-left

Margin start of the select popover list

Property Default Description
$select-ios-padding-top $item-ios-padding-top

Padding top of the select

$select-ios-padding-end $select-ios-padding-right

Padding end of the select

$select-ios-padding-bottom $item-ios-padding-bottom

Padding bottom of the select

$select-ios-padding-start $select-ios-padding-left

Padding start of the select

$select-ios-icon-color #999

Color of the select icon

$select-ios-placeholder-color $select-ios-icon-color

Color of the select placeholder

Property Default Description
$select-md-padding-top $item-md-padding-top

Padding top of the select

$select-md-padding-end $select-md-padding-right

Padding end of the select

$select-md-padding-bottom $item-md-padding-bottom

Padding bottom of the select

$select-md-padding-start $select-md-padding-left

Padding start of the select

$select-md-icon-color #999

Color of the select icon

$select-md-placeholder-color $select-md-icon-color

Color of the select placeholder

Property Default Description
$select-wp-padding-vertical 0

Padding top and bottom of the select

$select-wp-padding-horizontal ($item-wp-padding-end / 2)

Padding start/end of the select

$select-wp-margin-top $item-wp-padding-top

Margin top of the select

$select-wp-margin-end $select-wp-margin-right

Margin end of the select

$select-wp-margin-bottom $item-wp-padding-bottom

Margin bottom of the select

$select-wp-margin-start $select-wp-margin-left

Margin start of the select

$select-wp-border-width 2px

Border width of the select

$select-wp-border-color $input-wp-border-color

Border color of the select

$select-wp-icon-width 18px

Width of the select icon

$select-wp-icon-arrow-width 2px

Width of the select icon arrow

$select-wp-icon-color $select-wp-border-color

Color of the select icon

$select-wp-placeholder-color $select-wp-icon-color

Color of the select placeholder

API

Native

General