Selects are form controls to select an option, or options, from a set of options, similar to a native <select> element. When a user taps the select, a dialog appears with all of the options in a large, easy to select list.

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

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

Interfaces

By default, 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 Selection

By default, the select allows the user to select 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 select component's value receives the value of the selected option's value.

Multiple Selection

By adding the multiple attribute to 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 select component's value receives an array of all of the selected option values.

Note: the action-sheet and popover interfaces will not work with multiple selection.

Select Buttons

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

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 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 header, subheader, css class, and more. See the AlertController API docs, ActionSheetController API docs, and PopoverController API docs for the properties that each interface accepts.

Properties

Property	Attribute	Description	Type
`cancelText`	`cancel-text`	The text to display on the cancel button. Default: `Cancel`.	`string`
`disabled`	`disabled`	If true, the user cannot interact with the select. Defaults to `false`.	`boolean`
`interfaceOptions`	--	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.	`any`
`interface`	`interface`	The interface the select should use: `action-sheet`, `popover` or `alert`. Default: `alert`.	`SelectInterface`
`mode`	`mode`	The mode determines which platform styles to use. Possible values are: `"ios"` or `"md"`.	`Mode`
`multiple`	`multiple`	If true, the select can accept multiple values.	`boolean`
`name`	`name`	The name of the control, which is submitted with the form data.	`string`
`okText`	`ok-text`	The text to display on the ok button. Default: `OK`.	`string`
`placeholder`	`placeholder`	The text to display when the select is empty.	`string`
`selectedText`	`selected-text`	The text to display instead of the selected option's value.	`string`
`value`	--	the value of the select.	`any`, `null`

Events

Event	Description
`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.

Methods

Method	Description
`open`

CSS Custom Properties

Name	Description
`--color`	Color of the select text
`--icon-color`	Color of the select icon
`--padding-bottom`	Bottom padding of the select
`--padding-end`	End padding of the select
`--padding-start`	Start padding of the select
`--padding-top`	Top padding of the select
`--placeholder-color`	Color of the select placeholder text

Built with StencilJS