バージョン: v8

ion-select

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

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

Label Placement

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.

Label Slot

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.

No Visible Label

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

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.

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

Multiple Selection

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.

注記

The action-sheet interface is not supported with multiple selection.

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

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, 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.

Alert

Action Sheet

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.

Console

Console messages will appear here when logged from the example above.

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 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.

Using compareWith

Console

Console messages will appear here when logged from the example above.

Object Values and Multiple Selection

Console

Console messages will appear here when logged from the example above.

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".

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

警告

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

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.

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.

Interface Options

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.

Start and End Slots

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.

注記

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.

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 styling sections (CSS shadow parts, CSS custom properties, and slots) 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.

Custom Toggle Icons

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

Icon Flip Behavior

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.

Typeahead Component

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.

Helper & Error Text

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.

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

Accessibility

Keyboard Interactions

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.

Key	Description
`Enter`	Opens the overlay and focuses on the first selected option. If there is no selected option, then it focuses on the first option.
`Space`	Opens the overlay and focuses on the first selected option. If there is no selected option, then it focuses on the first option.

Single Selection

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.

Key	Description
`ArrowDown`	Focuses and selects the next option in the list. If there is no next option, selection will cycle to the first option.
`ArrowLeft`	Focuses and selects the previous option in the list. If there is no previous option, selection will cycle to the last option.
`ArrowRight`	Focuses and selects the next option in the list. If there is no next option, selection will cycle to the first option.
`ArrowUp`	Focuses and selects the previous option in the list. If there is no previous option, selection will cycle to the last option.
`Enter`	If an option is focused, it will select the option. Overlays without an 'OK' button will commit the value immediately, dismiss the overlay and return focus to the `ion-select` element. If the 'OK' button is focused, it will save the user's selection, dismiss the overlay and return focus to the `ion-select` element.
`Escape`	Closes the overlay without changing the submitted option. Returns the focus back to the `ion-select` element.
`Space`	If the focused radio button is not checked, unchecks the currently checked radio button and checks the focused radio button. Otherwise, does nothing. If the overlay does not have an 'OK' button, the value will be committed immediately and the overlay will dismiss.
`Tab`	Moves focus to the next focusable element (cancel button, 'OK' button, or either the selection or the first option) on the overlay. If the next focusable element is an option, then it will focus on the selected option, otherwise it will focus the first option.

Multiple Selection

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.

Key	Description
`Enter`	When the 'OK' button is focused, it will save the user's selection, dismiss the overlay, and return focus to the `ion-select` element.
`Escape`	Closes the overlay without changing the submitted option(s). Returns the focus back to the `ion-select` element.
`Space`	Selects or deselects the currently focused option. This does not deselect the other selected options. If the overlay does not have an 'OK' button, the value will be committed immediately.
`Tab`	Move focus to the next focusable element (cancel button, 'OK' button, or any of the options) on the overlay. If the next focusable element is the options list, then it should iterate through each option.

Properties

cancelText

Description	キャンセルボタンに表示するテキストです。
Attribute	`cancel-text`
Type	`string`
Default	`'Cancel'`

color

Description	アプリケーションのカラーパレットから使用する色を指定します。デフォルトのオプションは以下の通りです：`"primary"`, `"secondary"`, `"tertiary"`, `"success"`, `"warning"`, `"danger"`, `"light"`, `"medium"`, と `"dark"` です．色についての詳細は theming を参照してください。このプロパティは、modern select構文を使用する場合にのみ利用可能です。
Attribute	`color`
Type	`"danger" ｜ "dark" ｜ "light" ｜ "medium" ｜ "primary" ｜ "secondary" ｜ "success" ｜ "tertiary" ｜ "warning" ｜ string ｜ undefined`
Default	`undefined`

compareWith

Description	このプロパティを使用すると、開発者は、ion-select で選択されたオプションを決定するときにオブジェクトを比較するためのカスタム関数またはプロパティ名を指定できます。指定しない場合、デフォルトの動作では比較に厳密な等式 (===) が使用されます。
Attribute	`compare-with`
Type	`((currentValue: any, compareValue: any) => boolean) ｜ null ｜ string ｜ undefined`
Default	`undefined`

disabled

Description	`true`の場合、ユーザはセレクトと対話することができません。
Attribute	`disabled`
Type	`boolean`
Default	`false`

errorText

Description	Text that is placed under the select and displayed when an error is detected.
Attribute	`error-text`
Type	`string ｜ undefined`
Default	`undefined`

expandedIcon

Description	セレクトが開いているときに表示するトグルアイコン。定義されている場合、`md`モードでのアイコン回転の動作は無効になる。未定義の場合、セレクトが開いているときも閉じているときも `toggleIcon` が使用される。
Attribute	`expanded-icon`
Type	`string ｜ undefined`
Default	`undefined`

fill

Description	アイテムの塗りつぶし。もし `"solid"` ならば、アイテムは背景を持つようになります。もし `"outline"` ならば、アイテムはボーダー付きの透明なものになります。`md`モードでのみ使用可能です。
Attribute	`fill`
Type	`"outline" ｜ "solid" ｜ undefined`
Default	`undefined`

helperText

Description	Text that is placed under the select and displayed when no error is detected.
Attribute	`helper-text`
Type	`string ｜ undefined`
Default	`undefined`

interface

Description	セレクトが使用するインターフェース：action-sheet`,` popover`,` alert`, または` modal`.
Attribute	`interface`
Type	`"action-sheet" ｜ "alert" ｜ "modal" ｜ "popover"`
Default	`'alert'`

interfaceOptions

Description	alert`、`action-sheet`、`popover`インターフェースが取ることができる追加オプション。各インターフェイスの作成オプションについては、[ion-alert docs](./alert), [ion-action-sheet docs](./action-sheet), [ion-popover docs](./popover), [ion-modal docs](./modal) を参照してください。注意:`interfaceOptions`は`alert`インターフェイスの`inputs`や`buttons` を上書きしない。
Attribute	`interface-options`
Type	`any`
Default	`{}`

justify

Description	ラベルとセレクトを1行にまとめる方法。`labelPlacement`が `"floating"` または `"stacked"` に設定されている場合、ラベルとセレクトが異なる行にあるときは `justify` は適用されません。`"start"`：ラベルとセレクトはLTRでは左側に、RTLでは右側に表示されます。`"end"`：ラベルとセレクトはLTRでは右に、RTLでは左に表示されます。"space-between"`：ラベルとセレクトは行の反対側の端に表示され、2つの要素の間にはスペースがあります。
Attribute	`justify`
Type	`"end" ｜ "space-between" ｜ "start" ｜ undefined`
Default	`undefined`

label

Description	セレクトに関連付けられた可視ラベル。プレーンテキストのラベルをレンダリングする必要がある場合に使用する。 `label`プロパティは `label` スロットよりも優先される。
Attribute	`label`
Type	`string ｜ undefined`
Default	`undefined`

labelPlacement

Description	セレクトに対してラベルを配置する位置。`"start"`：ラベルはLTRではセレクトの左側に、RTLでは右側に表示されます。`"end"`：ラベルはLTRではセレクトの右側に、RTLでは左側に表示されます。"floating"`：ラベルは、セレクトがフォーカスされているか、セレクトに値がある場合、小さく表示され、セレクトの上に表示されます。それ以外の場合は、セレクトの上に表示されます。"stacked"`：ラベルは、セレクトがぼやけた状態や値がない状態でも、小さく表示され、セレクトの上に表示されます。`"fixed"`：ラベルの幅が固定される以外は、`"start"`と同じ動作になります。長いテキストは省略記号（"..."）で切り捨てられます。`"floating"`や "stacked"`を使用する場合は、selectに` value`か`placeholder` のどちらかを指定して初期化することをお勧めします。
Attribute	`label-placement`
Type	`"end" ｜ "fixed" ｜ "floating" ｜ "stacked" ｜ "start" ｜ undefined`
Default	`'start'`

mode

Description	modeは、どのプラットフォームのスタイルを使用するかを決定します。 This is a virtual property that is set once during initialization and will not update if you change its value after the initial render.
Attribute	`mode`
Type	`"ios" ｜ "md"`
Default	`undefined`

multiple

Description	`true`の場合、selectは複数の値を受け入れることができる。
Attribute	`multiple`
Type	`boolean`
Default	`false`

name

Description	フォームデータとともに送信されるコントロールの名前。
Attribute	`name`
Type	`string`
Default	`this.inputId`

okText

Description	okボタンに表示するテキストです。
Attribute	`ok-text`
Type	`string`
Default	`'OK'`

placeholder

Description	セレクトが空のときに表示するテキストです。
Attribute	`placeholder`
Type	`string ｜ undefined`
Default	`undefined`

required

Description	true の場合、スクリーンリーダーは必須項目として読み上げます。このプロパティはアクセシビリティ目的でのみ機能し、値が無効でもフォーム送信は妨げません。
Attribute	`required`
Type	`boolean`
Default	`false`

selectedText

Description	選択されたオプションの値の代わりに表示するテキストです。
Attribute	`selected-text`
Type	`null ｜ string ｜ undefined`
Default	`undefined`

shape

Description	セレクトの形状を指定します。`round`の場合、境界線の半径が大きくなります。
Attribute	`shape`
Type	`"round" ｜ undefined`
Default	`undefined`

toggleIcon

Description	使用するトグルアイコン。デフォルトは `ios` モードの場合は `chevronExpand` で、`md` モードの場合は `caretDownSharp` である。
Attribute	`toggle-icon`
Type	`string ｜ undefined`
Default	`undefined`

value

Description	セレクトの値です。
Attribute	`value`
Type	`any`
Default	`undefined`

Events

Name	Description	Bubbles
`ionBlur`	セレクトのフォーカスが外れたときに発行されます。	`true`
`ionCancel`	選択がキャンセルされたときに発行されます。	`true`
`ionChange`	値が変更されたときに発行される。プログラムで `value` プロパティを設定した場合は、このイベントは発生しない。	`true`
`ionDismiss`	オーバーレイが解除されたときに発行されます。	`true`
`ionFocus`	セレクトにフォーカスが当たったときに発行されます。	`true`

Methods

open

Description	セレクトオーバーレイを開きます。オーバーレイは `ion-select` の `interface` プロパティによって、アラート、アクションシート、ポップオーバーのいずれかになります。
Signature	`open(event?: UIEvent) => Promise<any>`
Parameters	event: The user interface event that called the open.

CSS Shadow Parts

Name	Description
`container`	セレクトテキストまたはプレースホルダーのコンテナ。
`error-text`	Supporting text displayed beneath the select when the select is invalid and touched.
`helper-text`	Supporting text displayed beneath the select when the select is valid.
`icon`	セレクトアイコンのコンテナです。
`label`	セレクトを表すラベルテキスト。
`placeholder`	値がないときにセレクトに表示されるテキスト。
`supporting-text`	Supporting text displayed beneath the select.
`text`	セレクトの表示値です。

CSS Custom Properties

Name	Description
`--background`	セレクトの背景
`--border-color`	セレクトボーダーの色
`--border-radius`	選択枠の半径。fill="outline "を使う場合、半径が大きいと表示が不均一になることがあります。
`--border-style`	セレクトボーダーのスタイル
`--border-width`	セレクトボーダーの幅
`--highlight-color-focused`	フォーカス時のセレクトのハイライトの色
`--highlight-color-invalid`	無効時のセレクトのハイライトの色
`--highlight-color-valid`	有効時のセレクトのハイライトの色
`--highlight-height`	セレクトのハイライトの高さ。mdモードにのみ適用される。
`--padding-bottom`	セレクトのBottom Padding
`--padding-end`	セレクトの方向が左から右の場合はRight Padding、右から左の場合はLeft Paddingを行う
`--padding-start`	セレクトの方向が左から右の場合はLeft Padding、右から左の場合はRight Padding
`--padding-top`	セレクトのTop Padding
`--placeholder-color`	セレクトPlaceholderテキストの色
`--placeholder-opacity`	セレクトPlaceholderテキストの不透明度
`--ripple-color`	MDモード時のリップルエフェクトの色です。

Name	Description
`--background`	セレクトの背景
`--border-color`	セレクトボーダーの色
`--border-radius`	選択枠の半径。fill="outline "を使う場合、半径が大きいと表示が不均一になることがあります。
`--border-style`	セレクトボーダーのスタイル
`--border-width`	セレクトボーダーの幅
`--highlight-color-focused`	フォーカス時のセレクトのハイライトの色
`--highlight-color-invalid`	無効時のセレクトのハイライトの色
`--highlight-color-valid`	有効時のセレクトのハイライトの色
`--highlight-height`	セレクトのハイライトの高さ。mdモードにのみ適用される。
`--padding-bottom`	セレクトのBottom Padding
`--padding-end`	セレクトの方向が左から右の場合はRight Padding、右から左の場合はLeft Paddingを行う
`--padding-start`	セレクトの方向が左から右の場合はLeft Padding、右から左の場合はRight Padding
`--padding-top`	セレクトのTop Padding
`--placeholder-color`	セレクトPlaceholderテキストの色
`--placeholder-opacity`	セレクトPlaceholderテキストの不透明度
`--ripple-color`	MDモード時のリップルエフェクトの色です。

Slots

Name	Description
`end`	セレクトの最後尾に表示するコンテンツ。
`label`	セレクトに関連付けるラベルテキスト。`labelPlacement`プロパティを使用して、selectに対するラベルの位置を制御します。ラベルをカスタムHTMLでレンダリングする必要がある場合に使用します。
`start`	セレクトの最先端に表示するコンテンツ。

Labels​

Label Placement​

Label Slot​

No Visible Label​

Single Selection​

Multiple Selection​

Interfaces​

Alert​

Action Sheet​

Popover​

Modal​

Responding to Interaction​

Object Value References​

Using compareWith​

Object Values and Multiple Selection​

Justification​

Filled Selects​

Select Buttons​

Interface Options​

Start and End Slots​

Customization​

Styling Select Element​

Styling Select Interface​

Custom Toggle Icons​

Icon Flip Behavior​

Typeahead Component​

Helper & Error Text​

Interfaces​

SelectChangeEventDetail​

SelectCustomEvent​

Accessibility​

Keyboard Interactions​

Single Selection​

Multiple Selection​

Properties​

cancelText​

color​

compareWith​

disabled​

errorText​

expandedIcon​

fill​

helperText​

interface​

interfaceOptions​

justify​

label​

labelPlacement​

mode​

multiple​

name​

okText​

placeholder​

required​

selectedText​

shape​

toggleIcon​

value​

Events​

Methods​

open​

CSS Shadow Parts​

CSS Custom Properties​

Slots​

Contents

Labels

Label Placement

Label Slot

No Visible Label

Single Selection

Multiple Selection

Interfaces

Alert

Action Sheet

Popover

Modal

Responding to Interaction

Object Value References

Using compareWith

Object Values and Multiple Selection

Justification

Filled Selects

Select Buttons

Interface Options

Start and End Slots

Customization

Styling Select Element

Styling Select Interface

Custom Toggle Icons

Icon Flip Behavior

Typeahead Component

Helper & Error Text

Interfaces

SelectChangeEventDetail

SelectCustomEvent

Accessibility

Keyboard Interactions

Single Selection

Multiple Selection

Properties

cancelText

color

compareWith

disabled

errorText

expandedIcon

fill

helperText

interface

interfaceOptions

justify

label

labelPlacement

mode

multiple

name

okText

placeholder

required

selectedText

shape

toggleIcon

value

Events

Methods

open

CSS Shadow Parts

CSS Custom Properties

Slots