import Props from '@ionic-internal/component-api/v8/select/props.md'; import Events from '@ionic-internal/component-api/v8/select/events.md'; import Methods from '@ionic-internal/component-api/v8/select/methods.md'; import Parts from '@ionic-internal/component-api/v8/select/parts.md'; import CustomProps from '@ionic-internal/component-api/v8/select/custom-props.mdx'; import Slots from '@ionic-internal/component-api/v8/select/slots.md';

import EncapsulationPill from '@components/page/api/EncapsulationPill';

Selects are form controls to select an option, or options, from a set of options. 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.

Labels should be used to describe the select. They can be used visually, and they will also be read out by screen readers when the user is focused on the select. This makes it easy for the user to understand the intent of the select. Select has several ways to assign a label:

Select has several options for supplying a label for the component:

• label property: used for plaintext labels
• label slot: used for custom HTML labels
• aria-label: used to provide a label for screen readers but adds no visible label

Labels will take up the width of their content by default. Developers can use the labelPlacement property to control how the label is placed relative to the control. While the label property is used here, labelPlacement can also be used with the label slot.

import LabelPlacement from '@site/static/usage/v8/select/label-placement/index.md';

While plaintext labels should be passed in via the label property, if custom HTML is needed, it can be passed through the label slot instead.

import LabelSlot from '@site/static/usage/v8/select/label-slot/index.md';

If no visible label is needed, developers should still supply an aria-label so the select is accessible to screen readers.

import NoVisibleLabel from '@site/static/usage/v8/select/no-visible-label/index.md';

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.

Keyboard interactions for single selection are described in the Keyboard Interactions section below.

import SingleSelectionExample from '@site/static/usage/v8/select/basic/single-selection/index.md';

By adding the multiple attribute to select, users are able to select multiple options. When multiple options can be selected, the alert, popover, or modal 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 interface is not supported with multiple selection.

:::

Keyboard interactions for multiple selection are described in the Keyboard Interactions section below.

import MultipleSelectionExample from '@site/static/usage/v8/select/basic/multiple-selection/index.md';

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, ion-popover, or ion-modal by passing action-sheet, popover, or modal, respectively, to the interface property. Read on to the other sections for the limitations of the different interfaces.

import AlertExample from '@site/static/usage/v8/select/basic/single-selection/index.md';

import ActionSheetExample from '@site/static/usage/v8/select/interfaces/action-sheet/index.md';

import PopoverExample from '@site/static/usage/v8/select/interfaces/popover/index.md';

import ModalExample from '@site/static/usage/v8/select/interfaces/modal/index.md';

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.

import RespondingToInteractionExample from '@site/static/usage/v8/select/basic/responding-to-interaction/index.md';

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 strict equality (===) to determine if an option is selected. This can be overridden by providing a property name or a function to the compareWith property.

import UsingCompareWithExample from '@site/static/usage/v8/select/objects-as-values/using-comparewith/index.md';

import ObjectValuesAndMultipleSelectionExample from '@site/static/usage/v8/select/objects-as-values/multiple-selection/index.md';

Developers can use the justify property to control how the label and control are packed on a line.

import JustifyExample from '@site/static/usage/v8/select/justify/index.md';

Material Design offers filled styles for a select. The fill property on the select can be set to either "solid" or "outline".

Filled selects can be used on iOS by setting the select's mode to md.

:::warning Selects that use fill should not be used in an ion-item due to styling conflicts between the components. :::

import FillExample from '@site/static/usage/v8/select/fill/index.md';

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.

The modal interface has a single Close button in the header. This button is only responsible for dismissing the modal. Any selections made will persist after clicking this button or if the modal is dismissed using an alternative method.

import ButtonTextExample from '@site/static/usage/v8/select/customization/button-text/index.md';

Since select uses the alert, action sheet, popover, and modal 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, ion-popover docs, and ion-modal docs for the properties that each interface accepts.

Note: interfaceOptions will not override inputs or buttons with the alert interface.

import InterfaceOptionsExample from '@site/static/usage/v8/select/customization/interface-options/index.md';

The start and end slots can be used to place icons, buttons, or prefix/suffix text on either side of the select. If the slot content is clicked, the select will not open.

:::note In most cases, Icon components placed in these slots should have aria-hidden="true". See the Icon accessibility docs for more information.

If slot content is meant to be interacted with, it should be wrapped in an interactive element such as a Button. This ensures that the content can be tabbed to. :::

import StartEndSlots from '@site/static/usage/v8/select/start-end-slots/index.md';

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.

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.

import StylingSelectExample from '@site/static/usage/v8/select/customization/styling-select/index.md';

Customizing the interface dialog should be done by following the styling sections (CSS shadow parts, CSS custom properties, and slots) in that interface's documentation:

• Alert
• Action Sheet
• Popover
• Modal

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.

The icon that displays next to the select text can be set to any Ionicon using the toggleIcon and/or expandedIcon properties.

import CustomToggleIconsExample from '@site/static/usage/v8/select/customization/custom-toggle-icons/index.md';

By default, when the select is open, the toggle icon will automatically rotate on md mode and remain static on ios mode. This behavior can be customized using CSS.

The below example also uses a custom toggleIcon to better demonstrate the flip behavior on ios, since the default icon is vertically symmetrical.

import IconFlipBehaviorExample from '@site/static/usage/v8/select/customization/icon-flip-behavior/index.md';

Typeahead or autocomplete functionality can be built using existing Ionic components. We recommend using an ion-modal to make the best use of the available screen space.

import TypeaheadExample from '@site/static/usage/v8/select/typeahead/index.md';

Helper and error text can be used inside of a select with the helperText and errorText property. The error text will not be displayed unless the ion-invalid and ion-touched classes are added to the ion-select. This ensures errors are not shown before the user has a chance to enter data.

In Angular, this is done automatically through form validation. In JavaScript, React and Vue, the class needs to be manually added based on your own validation.

import HelperError from '@site/static/usage/v8/select/helper-error/index.md';

interface SelectChangeEventDetail<T = any> {
  value: T;
}

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;
}

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.

Developers can perform this migration one select at a time. While developers can continue using the legacy syntax, we recommend migrating as soon as possible.

Using the modern syntax involves two steps:

1. Remove ion-label and use the label property on ion-select instead. The placement of the label can be configured using the labelPlacement property on ion-select.
2. Move any usage of fill and shape from ion-item on to ion-select.

import Migration from '@site/static/usage/v8/select/migration/index.md';

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.

Ionic's keyboard interactions follow the implementation patterns of the web instead of the native iOS select for a consistent experience across all platforms.

These keyboard interactions apply to all ion-select elements when the following conditions are met:

• The select is closed.
• The select is focused.
• The select is not disabled.

Single selection keyboard interaction follows the ARIA implementation patterns of a radio.

These keyboard interactions apply to ion-action-sheet, ion-alert, ion-popover, and ion-modal elements when the overlay is presented and focused.

Multiple selection keyboard interaction follows the ARIA implementation patterns of a checkbox.

These keyboard interactions apply to ion-alert, ion-popover, and ion-modal elements when the overlay is presented and multiple selection is enabled.