The <ion-select> element is similar to a native <select> element, however, it is easier for users to sort through and select the preferred option or options. When a user taps the select component, a dialog appears with all of the options in a large, easy to select list.

It should be used with child ion-select-option elements. If the child option is not given a value attribute then it will use its text as the value.

If value is set on the ion-select, the selected option will be based on that value. Otherwise, the selected attribute can be used on the ion-select-option elements.

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. The ion-select component's value receives the value of the selected option's value.

<ion-item>
  <ion-label>Gender</ion-label>
  <ion-select id="gender">
    <ion-select-option value="f">Female</ion-select-option>
    <ion-select-option value="m">Male</ion-select-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 component's value receives an array of all the selected option values. In the example below, because each option is not given a value, it will use the option's text as the value.

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

<ion-item>
  <ion-label>Toppings</ion-label>
  <ion-select id="toppings" multiple="true">
    <ion-select-option>Bacon</ion-select-option>
    <ion-select-option>Black Olives</ion-select-option>
    <ion-select-option>Extra Cheese</ion-select-option>
    <ion-select-option>Mushrooms</ion-select-option>
    <ion-select-option>Pepperoni</ion-select-option>
    <ion-select-option>Sausage</ion-select-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 ok-text="Okay" cancel-text="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. The popover interface does not have a Cancel button, clicking on the backdrop will close the overlay.

Interface Options

Since ion-select uses the Alert, Action Sheet and Popover interfaces, options can be passed to these components through the interfaceOptions 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 title and subTitle of the overlay, pass it into interfaceOptions.

<ion-select id="customSelect">
  ...
</ion-select>

var customSelect = document.getElementById('customSelect');
customSelect.interfaceOptions = {
  title: 'Pizza Toppings',
  subTitle: 'Select your toppings'
};

Properties

cancelText

string

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

disabled

boolean

If true, the user cannot interact with the select. Defaults to false.

interface

string

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

interfaceOptions

any

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

multiple

boolean

If true, the select can accept multiple values.

name

string

The name of the control, which is submitted with the form data.

okText

string

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

placeholder

string

The text to display when the select is empty.

selectedText

string

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

value

the value of the select.

Attributes

cancel-text

string

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

disabled

boolean

If true, the user cannot interact with the select. Defaults to false.

interface

string

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

interface-options

any

multiple

boolean

If true, the select can accept multiple values.

name

string

The name of the control, which is submitted with the form data.

ok-text

string

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

placeholder

string

The text to display when the select is empty.

selected-text

string

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

value

the value of the select.

Events

ionBlur

Emitted when the select loses focus.

ionCancel

Emitted when the selection is cancelled.

ionChange

Emitted when the value has changed.

ionFocus

Emitted when the select has focus.

ionStyle

Emitted when the styles change.

Built with StencilJS