ion-select
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.
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 select component's value receives the value of the selected option's value.
Interfaces
By default, select uses ion-alert to open up the overlay of options in an alert. The interface can be changed to use ion-action-sheet or ion-popover by passing action-sheet
or popover
, respectively, to the interface
property. Read on to the other sections for the limitations of the different interfaces.
Action Sheet
Popover
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.
Responding to Interaction
The main ways of handling user interaction with the select are the ionChange
, ionDismiss
, and ionCancel
events. See Events for more details on these and other events that select fires.
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.
By default, the select uses object equality (===
) to determine if an option is selected. This can be overridden by providing a property name or a function to the compareWith
property.
Using compareWith
Object Values and Multiple Selection
Label Positioning
Labels will take up the width of their content by default. This positioning can be changed to be a fixed width, stacked, or floating label.
Justification
Developers can use the justify
property to control how the label and control are packed on a line.
Filled Selects
Material Design offers filled styles for a select. The fill
property on the select can be set to either "solid"
or "outline"
.
Since the fill
styles visually defines the select container, selects that use fill
should not be used in ion-item
.
Select Buttons
The alert supports 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 ion-alert docs, ion-action-sheet docs, and ion-popover docs for the properties that each interface accepts.
Note: interfaceOptions
will not override inputs
or buttons
with the alert
interface.
Customization
There are two units that make up the Select component and each need to be styled separately. The ion-select
element is represented on the view by the selected value(s), or placeholder if there is none, and dropdown icon. The interface, which is defined in the Interfaces section above, is the dialog that opens when clicking on the ion-select
. The interface contains all of the options defined by adding ion-select-option
elements. The following sections will go over the differences between styling these.
Styling Select Element
As mentioned, the ion-select
element consists only of the value(s), or placeholder, and icon that is displayed on the view. To customize this, style using a combination of CSS and any of the CSS custom properties.
Alternatively, depending on the browser support needed, CSS shadow parts can be used to style the select. Notice that by using ::part
, any CSS property on the element can be targeted.
Styling Select Interface
Customizing the interface dialog should be done by following the Customization section in that interface's documentation:
However, the Select Option does set a class for easier styling and allows for the ability to pass a class to the overlay option, see the Select Options documentation for usage examples of customizing options.
Interfaces
SelectChangeEventDetail
interface SelectChangeEventDetail<T = any> {
value: T;
}
SelectCustomEvent
While not required, this interface can be used in place of the CustomEvent
interface for stronger typing with Ionic events emitted from this component.
interface SelectCustomEvent<T = any> extends CustomEvent {
detail: SelectChangeEventDetail<T>;
target: HTMLIonSelectElement;
}
Migrating from Legacy Select Syntax
A simpler select syntax was introduced in Ionic 7.0. This new syntax reduces the boilerplate required to setup an select, resolves accessibility issues, and improves the developer experience.
While developers can continue using the legacy syntax, we recommend migrating as soon as possible.
Using the Modern Syntax
Using the modern syntax involves two steps:
- Remove
ion-label
and use thelabel
property onion-select
instead. The placement of the label can be configured using thelabelPlacement
property onion-select
. - Move any usage of
fill
andshape
fromion-item
on toion-select
.
- JavaScript
- Angular
- React
- Vue
<!-- Label and Label Position -->
<!-- Before -->
<ion-item>
<ion-label position="floating">Favorite Fruit:</ion-label>
<ion-select>...</ion-select>
</ion-item>
<!-- After -->
<ion-item>
<ion-select label="Favorite Fruit:" label-placement="floating">...</ion-select>
</ion-item>
<!-- Fill -->
<!-- Before -->
<ion-item fill="outline" shape="round">
<ion-label position="floating">Favorite Fruit:</ion-label>
<ion-select>...</ion-select>
</ion-item>
<!-- After -->
<!-- Inputs using `fill` should not be placed in ion-item -->
<ion-select fill="outline" shape="round" label="Favorite Fruit:" label-placement="floating">...</ion-select>
<!-- Label and Label Position -->
<!-- Before -->
<ion-item>
<ion-label position="floating">Favorite Fruit:</ion-label>
<ion-select>...</ion-select>
</ion-item>
<!-- After -->
<ion-item>
<ion-select label="Favorite Fruit:" labelPlacement="floating">...</ion-select>
</ion-item>
<!-- Fill -->
<!-- Before -->
<ion-item fill="outline" shape="round">
<ion-label position="floating">Favorite Fruit:</ion-label>
<ion-select>...</ion-select>
</ion-item>
<!-- After -->
<!-- Inputs using `fill` should not be placed in ion-item -->
<ion-select fill="outline" shape="round" label="Favorite Fruit:" labelPlacement="floating">...</ion-select>
{/* Label and Label Position */}
{/* Before */}
<IonItem>
<IonLabel position="floating">Favorite Fruit:</IonLabel>
<IonSelect>...</IonSelect>
</IonItem>
{/* After */}
<IonItem>
<IonSelect label="Favorite Fruit:" labelPlacement="floating">...</IonSelect>
</IonItem>
{/* Fill */}
{/* Before */}
<IonItem fill="outline" shape="round">
<IonLabel position="floating">Favorite Fruit:</IonLabel>
<IonSelect>...</IonSelect>
</IonItem>
{/* After */}
{/* Inputs using `fill` should not be placed in IonItem */}
<IonSelect fill="outline" shape="round" label="Favorite Fruit:" labelPlacement="floating">...</IonSelect>
<!-- Label and Label Position -->
<!-- Before -->
<ion-item>
<ion-label position="floating">Favorite Fruit:</ion-label>
<ion-select>...</ion-select>
</ion-item>
<!-- After -->
<ion-item>
<ion-select label="Favorite Fruit:" label-placement="floating">...</ion-select>
</ion-item>
<!-- Fill -->
<!-- Before -->
<ion-item fill="outline" shape="round">
<ion-label position="floating">Favorite Fruit:</ion-label>
<ion-select>...</ion-select>
</ion-item>
<!-- After -->
<!-- Inputs using `fill` should not be placed in ion-item -->
<ion-select fill="outline" shape="round" label="Favorite Fruit:" label-placement="floating">...</ion-select>
Using the Legacy Syntax
Ionic uses heuristics to detect if an app is using the modern select syntax. In some instances, it may be preferable to continue using the legacy syntax. Developers can set the legacy
property on ion-select
to true
to force that instance of the input to use the legacy syntax.
Properties
cancelText
Description | The text to display on the cancel button. |
Attribute | cancel-text |
Type | string |
Default | 'Cancel' |
compareWith
Description | A property name or function used to compare object values |
Attribute | compare-with |
Type | ((currentValue: any, compareValue: any) => boolean) ο½ null ο½ string ο½ undefined |
Default | undefined |
disabled
Description | If true , the user cannot interact with the select. |
Attribute | disabled |
Type | boolean |
Default | false |
interface
Description | The interface the select should use: action-sheet , popover or alert . |
Attribute | interface |
Type | "action-sheet" ο½ "alert" ο½ "popover" |
Default | 'alert' |
interfaceOptions
Description | Any additional options that the alert , action-sheet or popover interface can take. See the ion-alert docs, the ion-action-sheet docs and the ion-popover docs for the create options for each interface.Note: interfaceOptions will not override inputs or buttons with the alert interface. |
Attribute | interface-options |
Type | any |
Default | {} |
mode
Description | The mode determines which platform styles to use. |
Attribute | mode |
Type | "ios" ο½ "md" |
Default | undefined |
multiple
Description | If true , the select can accept multiple values. |
Attribute | multiple |
Type | boolean |
Default | false |
name
Description | The name of the control, which is submitted with the form data. |
Attribute | name |
Type | string |
Default | this.inputId |
okText
Description | The text to display on the ok button. |
Attribute | ok-text |
Type | string |
Default | 'OK' |
placeholder
Description | The text to display when the select is empty. |
Attribute | placeholder |
Type | string ο½ undefined |
Default | undefined |
selectedText
Description | The text to display instead of the selected option's value. |
Attribute | selected-text |
Type | null ο½ string ο½ undefined |
Default | undefined |
value
Description | the value of the select. |
Attribute | value |
Type | any |
Default | undefined |
Events
Name | Description |
---|---|
ionBlur | Emitted when the select loses focus. |
ionCancel | Emitted when the selection is cancelled. |
ionChange | Emitted when the value has changed. |
ionDismiss | Emitted when the overlay is dismissed. |
ionFocus | Emitted when the select has focus. |
Methods
open
Description | Open the select overlay. The overlay is either an alert, action sheet, or popover, depending on the interface property on the ion-select . |
Signature | open(event?: UIEvent) => Promise<any> |
CSS Shadow Parts
Name | Description |
---|---|
icon | The select icon container. |
placeholder | The text displayed in the select when there is no value. |
text | The displayed value of the select. |
CSS Custom Properties
Name | Description |
---|---|
--padding-bottom | Bottom padding of the select |
--padding-end | Right padding if direction is left-to-right, and left padding if direction is right-to-left of the select |
--padding-start | Left padding if direction is left-to-right, and right padding if direction is right-to-left of the select |
--padding-top | Top padding of the select |
--placeholder-color | Color of the select placeholder text |
--placeholder-opacity | Opacity of the select placeholder text |
Slots
No slots available for this component.