scoped
The input component is a wrapper to the HTML input element with custom styling and additional functionality. It accepts most of the same properties as the HTML input and integrates with the keyboard on mobile devices.
The input component is meant for text type inputs only, such as "text", "password", "email", "number", "search", "tel", and "url". It supports all standard text input events including keyup, keydown, keypress, and more. The default type is "text".
Labels should be used to describe the input. They can be used visually, and they will also be read out by screen readers when the user is focused on the input. This makes it easy for the user to understand the intent of the input. Input has several ways to assign a label:
label property: used for plaintext labelslabel slot: used for custom HTML labels (experimental)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 plaintext labels should be passed in via the label property, if custom HTML is needed, it can be passed through the label slot instead.
Note that this feature is considered experimental because it relies on a simulated version of Web Component slots. As a result, the simulated behavior may not exactly match the native slot behavior.
If no visible label is needed, developers should still supply an aria-label so the input is accessible to screen readers.
Inputs offer two options for clearing the input based on how you interact with it. The first way is by adding the clearInput property which will show a clear button when the input has a value. The second way is the clearOnEdit property which will clear the input after it has been blurred and then typed in again. Inputs with a type set to "password" will have clearOnEdit enabled by default.
Material Design offers filled styles for an input. The fill property on the input can be set to either "solid" or "outline".
Filled inputs can be used on iOS by setting the input's mode to md.
Inputs that use fill should not be used in an ion-item due to styling conflicts between the components.
Helper & Error Text
Helper and error text can be used inside of an input 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-input. 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.
The input counter is text that displays under an input to notify the user of how many characters have been entered out of the total that the input will accept. When adding counter, the default behavior is to format the value that gets displayed as inputLength / maxLength. This behavior can be customized by passing in a formatter function to the counterFormatter property.
The counter and counterFormatter properties on ion-item were deprecated in Ionic 7 and should be used directly on ion-input instead.
Inputs with a counter add a border between the input and the counter, therefore they should not be placed inside of an ion-item which adds an additional border under the item. The ion-padding-start class can be added to align the counter inputs with inputs inside of items.
Developers can use the ionInput event to update the input value in response to user input such as a keypress. This is useful for filtering out invalid or unwanted characters.
When storing the value in a state variable, we recommend updating both the state variable and the ion-input component value. This ensures that the state variable and the ion-input component value remain in sync.
Input masks are expressions that constrain input to support valid input values. Ionic recommends using Maskito for input masking. Maskito is a lightweight, dependency-free library for masking input fields. It supports a wide range of masks, including phone numbers, credit cards, dates, and more.
To get started with Maskito, install the library:
npm install @maskito/core @maskito/{angular,react,vue}
The start and end slots can be used to place icons, buttons, or prefix/suffix text on either side of the input.
Note that this feature is considered experimental because it relies on a simulated version of Web Component slots. As a result, the simulated behavior may not exactly match the native slot behavior.
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.
Setting the color property changes the color palette for each input. On ios mode, this property changes the caret color. On md mode, this property changes the caret color and the highlight/underline color.
The color property does not change the text color of the input. For that, use the --color CSS property.
Input uses scoped encapsulation, which means it will automatically scope its CSS by appending each of the styles with an additional class at runtime. Overriding scoped selectors in CSS requires a higher specificity selector. Targeting the ion-input for customization will not work; therefore we recommend adding a class and customizing it that way.
interface InputChangeEventDetail {
value: string | undefined | null;
}
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 InputCustomEvent extends CustomEvent {
detail: InputChangeEventDetail;
target: HTMLIonInputElement;
}
| Description | テキスト値がユーザーによって入力／編集される際に、自動的に大文字にするかどうか、またどのようにするかについて示します。利用可能なオプション: "off", "none", "on", "sentences", "words", "characters". |
| Attribute | autocapitalize |
| Type | string |
| Default | 'off' |
| Description | コントロールの値が、ブラウザによって自動的に補完されるかどうかを示します。 |
| Attribute | autocomplete |
| Type | "name" ｜ "email" ｜ "tel" ｜ "url" ｜ "on" ｜ "off" ｜ "honorific-prefix" ｜ "given-name" ｜ "additional-name" ｜ "family-name" ｜ "honorific-suffix" ｜ "nickname" ｜ "username" ｜ "new-password" ｜ "current-password" ｜ "one-time-code" ｜ "organization-title" ｜ "organization" ｜ "street-address" ｜ "address-line1" ｜ "address-line2" ｜ "address-line3" ｜ "address-level4" ｜ "address-level3" ｜ "address-level2" ｜ "address-level1" ｜ "country" ｜ "country-name" ｜ "postal-code" ｜ "cc-name" ｜ "cc-given-name" ｜ "cc-additional-name" ｜ "cc-family-name" ｜ "cc-number" ｜ "cc-exp" ｜ "cc-exp-month" ｜ "cc-exp-year" ｜ "cc-csc" ｜ "cc-type" ｜ "transaction-currency" ｜ "transaction-amount" ｜ "language" ｜ "bday" ｜ "bday-day" ｜ "bday-month" ｜ "bday-year" ｜ "sex" ｜ "tel-country-code" ｜ "tel-national" ｜ "tel-area-code" ｜ "tel-local" ｜ "tel-extension" ｜ "impp" ｜ "photo" |
| Default | 'off' |
| Description | ユーザーがテキスト値を入力/編集する際に、自動補正を有効にするかどうか。 |
| Attribute | autocorrect |
| Type | "off" ｜ "on" |
| Default | 'off' |
| Description | ネイティブの入力要素に autofocus 属性 を設定します。 ページロード時に要素がフォーカスされるには、これだけでは不十分かもしれません。詳しくはmanaging focusを参照してください。 |
| Attribute | autofocus |
| Type | boolean |
| Default | false |
| Description | trueの場合、値があるときにInputにクリアアイコンが表示されます。これをクリックすると、入力がクリアされます。 |
| Attribute | clear-input |
| Type | boolean |
| Default | false |
| Description | クリアボタンに使用するアイコン。clearInputがtrue` に設定されている場合にのみ適用される。 |
| Attribute | clear-input-icon |
| Type | string ｜ undefined |
| Default | undefined |
| Description | trueの場合、編集時にフォーカスされた後、値がクリアされる。デフォルトは type が "password" のとき true で、それ以外のときは false です。 |
| Attribute | clear-on-edit |
| Type | boolean ｜ undefined |
| Default | undefined |
| Description | アプリケーションのカラーパレットから使用する色を指定します。デフォルトのオプションは以下の通りです。 "primary", "secondary", "tertiary", "success", "warning", "danger", "light", "medium", と "dark" です．色に関する詳しい情報は theming を参照してください。 |
| Attribute | color |
| Type | "danger" ｜ "dark" ｜ "light" ｜ "medium" ｜ "primary" ｜ "secondary" ｜ "success" ｜ "tertiary" ｜ "warning" ｜ string ｜ undefined |
| Default | undefined |
| Description | trueの場合、文字カウンタが使用された文字の比率と総文字数制限を表示します。カウンターを正しく計算するために、開発者は maxlength プロパティも設定する必要があります。 |
| Attribute | counter |
| Type | boolean |
| Default | false |
| Description | キーを押すたびに ionInput イベントが発生するまでの待ち時間をミリ秒単位で設定します。 |
| Attribute | debounce |
| Type | number ｜ undefined |
| Default | undefined |
| Description | trueの場合、ユーザはInputと対話することができません。 |
| Attribute | disabled |
| Type | boolean |
| Default | false |
| Description | どのエンターキーを表示するかのブラウザへのヒント。指定可能な値。"enter", "done", "go", "next", "previous", "search", and "send". |
| Attribute | enterkeyhint |
| Type | "done" ｜ "enter" ｜ "go" ｜ "next" ｜ "previous" ｜ "search" ｜ "send" ｜ undefined |
| Default | undefined |
errorText
| Description | Inputの下に配置され、エラーが検出されたときに表示されるテキストです。 |
| Attribute | error-text |
| Type | string ｜ undefined |
| Default | undefined |
| Description | アイテムの塗りつぶし。もし "solid" ならば、アイテムは背景を持つようになります。もし "outline" ならば、アイテムはボーダー付きの透明なものになります。mdモードでのみ使用可能です。 |
| Attribute | fill |
| Type | "outline" ｜ "solid" ｜ undefined |
| Default | undefined |
helperText
| Description | Inputの下に配置され、エラーが検出されなかった場合に表示されるテキストです。 |
| Attribute | helper-text |
| Type | string ｜ undefined |
| Default | undefined |
| Description | どのキーボードを表示するかのブラウザへのヒント。指定可能な値。"none", "text", "tel", "url", "email", "numeric", "decimal", and "search". |
| Attribute | inputmode |
| Type | "decimal" ｜ "email" ｜ "none" ｜ "numeric" ｜ "search" ｜ "tel" ｜ "text" ｜ "url" ｜ undefined |
| Default | undefined |
| Description | 入力に関連付けられた可視ラベル。 プレーンテキストのラベルをレンダリングする必要がある場合に使用する。 両方が使用されている場合、label プロパティが label スロットよりも優先される。 |
| Attribute | label |
| Type | string ｜ undefined |
| Default | undefined |
| Description | 入力に対してラベルを配置する位置。"start"：ラベルはLTRでは入力の左側に、RTLでは右側に表示されます。"end"：ラベルはLTRでは入力の右側、RTLでは左側に表示されます。"floating"："floating"：ラベルは、入力にフォーカスが当たっているときや、入力に値があるときは小さく表示され、入力の上に表示されます。それ以外の場合は、入力の上に表示されます。"スタック(stacked)"：入力がぼやけた状態や値がない場合でも、ラベルは小さく表示され、入力の上に表示されます。"fixed"：ラベルの幅が固定される以外は、"start"`と同じ動作になります。長いテキストは省略記号（"..."）で切り捨てられます。 |
| Attribute | label-placement |
| Type | "end" ｜ "fixed" ｜ "floating" ｜ "stacked" ｜ "start" |
| Default | 'start' |
| Description | 最大値で、その最小値（min属性）より小さくてはなりません。 |
| Attribute | max |
| Type | number ｜ string ｜ undefined |
| Default | undefined |
| Description | type属性の値が text, email, search, password, tel, または url の場合、この属性はユーザーが入力できる最大文字数を指定します。 |
| Attribute | maxlength |
| Type | number ｜ undefined |
| Default | undefined |
| Description | 最小値で、その最大値（max属性）より大きくてはなりません。
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 | min |
| Type | number ｜ string ｜ undefined |
| Default | undefined |
| Description | type属性の値が text, email, search, password, tel, または url の場合、この属性はユーザーが入力できる最小文字数を指定します。 |
| Attribute | minlength |
| Type | number ｜ undefined |
| Default | undefined |
| 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 |
| Description | trueの場合、ユーザは複数の値を入力することができる。この属性は、type属性が "email" に設定されている場合に適用され、それ以外の場合は無視される。 |
| Attribute | multiple |
| Type | boolean ｜ undefined |
| Default | undefined |
| Description | フォームデータとともに送信されるコントロールの名前。 |
| Attribute | name |
| Type | string |
| Default | this.inputId |
| Description | 値をチェックするための正規表現。パターンは、部分的なものだけでなく、値全体にマッチする必要があります。title 属性を使って、ユーザーを助けるためにパターンを説明します。この属性は、type属性の値が "text", "search", "tel", "url", "email", "date", または "password" であるときに適用され、それ以外のときは無視されます。type 属性が "date" の場合、pattern は "date" Inputタイプをネイティブにサポートしないブラウザでのみ使用されます。詳しくは https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/date を参照してください。 |
| Attribute | pattern |
| Type | string ｜ undefined |
| Default | undefined |
| Description | Inputが値を持つ前に表示される指示テキスト。このプロパティは、typeプロパティが "email", "number", "password", "search", "tel", "text", または "url" に設定されている場合にのみ適用され、それ以外は無視されます。 |
| Attribute | placeholder |
| Type | string ｜ undefined |
| Default | undefined |
| Description | trueの場合、ユーザーは値を変更することができません。 |
| Attribute | readonly |
| Type | boolean |
| Default | false |
| Description | trueの場合、ユーザーはフォームを送信する前に値を入力する必要があります。 |
| Attribute | required |
| Type | boolean |
| Default | false |
| Description | 入力の形状を指定します。"round"の場合、境界線の半径が大きくなります。 |
| Attribute | shape |
| Type | "round" ｜ undefined |
| Default | undefined |
| Description | trueの場合、その要素のスペルチェックと文法チェックが行われる。 |
| Attribute | spellcheck |
| Type | boolean |
| Default | false |
| Description | min属性、max属性と連携して、値を設定する際の増分を制限することができます。設定可能な値は以下の通りです。"any"または正の浮動小数点数。 |
| Attribute | step |
| Type | string ｜ undefined |
| Default | undefined |
| Description | 表示するコントロールの種類を指定します。デフォルトのタイプはテキストです。 |
| Attribute | type |
| Type | "date" ｜ "datetime-local" ｜ "email" ｜ "month" ｜ "number" ｜ "password" ｜ "search" ｜ "tel" ｜ "text" ｜ "time" ｜ "url" ｜ "week" |
| Default | 'text' |
| Description | 入力された値です。 |
| Attribute | value |
| Type | null ｜ number ｜ string ｜ undefined |
| Default | '' |
| Name | Description | Bubbles |
|---|
ionBlur | Inputのフォーカスが外れたときに発行されます。 | true |
ionChange | ionChange イベントは、ユーザが入力値を変更したときに発生する。ionInput イベントとは異なり、ionChange イベントは変更がコミットされたときにのみ発生する。 ユーザが明示的に変更をコミットしたとき (例えば、<ion-input type="date"> の日付ピッカーから日付を選択したり、"Enter" キーを押したりしたときなど)。- 値が変更された後、要素がフォーカスを失ったとき。 このイベントは、プログラムで value プロパティを設定する場合には発生しません。 | true |
ionFocus | Inputにフォーカスが当たったときに発行されます。 | true |
ionInput | ionInput イベントは、ユーザが入力値を変更するたびに発生する。ionChange イベントとは異なり、 ionInput イベントは入力値が変更されるたびに発生する。これは通常、ユーザが入力を行うたびに発生します。 テキスト入力を受け付ける要素(type=text, type=telなど)の場合、インターフェイスはInputEventとなります。その他の要素の場合、インターフェイスはEventとなります。編集時に入力がクリアされる場合、型は null となる。 | true |
| Description | 要素の内部で使用されているネイティブの <input> 要素を返します。 |
| Signature | getInputElement() => Promise<HTMLInputElement> |
| Description | ion-input のネイティブ input にフォーカスを設定する。グローバルな input.focus() の代わりにこのメソッドを使用する。 ページ入力時に入力にフォーカスを当てたい場合は、 ionViewDidEnter() ライフサイクルメソッド内で setFocus() を呼び出す必要がある。 オーバーレイが表示されたときに入力にフォーカスを当てたい開発者は、 didPresent が解決した後に setFocus を呼び出してください。 詳細については、managing focusを参照してください。 |
| Signature | setFocus() => Promise<void> |
No CSS shadow parts available for this component.
| Name | Description |
|---|
--background | Inputの背景 |
--border-color | ヘルパーテキスト、エラーテキスト、カウンターを使用する場合のInput下のボーダーの色 |
--border-radius | 入力の半径。fill="outline "を使う場合、半径が大きいと表示が不 均一 になることがある。 |
--border-style | ヘルパーテキスト、エラーテキスト、カウンターを使用する場合の入力下のボーダーのスタイル |
--border-width | ヘルパーテキスト、エラーテキスト、カウンターを使用する場合の入力下のボーダーの幅 |
--color | Inputのテキストの色 |
--highlight-color-focused | フォーカスされたときの入力のハイライトの色 |
--highlight-color-invalid | 入力が無効な場合のハイライトの色 |
--highlight-color-valid | 有効時の入力のハイライトの色 |
--highlight-height | 入力のハイライトの高さ。mdモードにのみ適用される。 |
--padding-bottom | InputのBottom Padding |
--padding-end | 入力の方向が左から右の場合はRight Padding、右から左の場合はLeft Paddingとなります。 |
--padding-start | 入力の方向が左から右の場合はLeft Padding、右から左の場合はRight Paddingとなります。 |
--padding-top | InputのTop Padding |
--placeholder-color | InputのPlaceholderテキストの色 |
--placeholder-font-style | InputのPlaceholderテキストのFont Style |
--placeholder-font-weight | InputのPlaceholderテキストのFont Weight |
--placeholder-opacity | InputのPlaceholderテキストの不透明度 |
| Name | Description |
|---|
--background | Inputの背景 |
--border-color | ヘルパーテキスト、エラーテキスト、カウンターを使用する場合のInput下のボーダーの色 |
--border-radius | 入力の半径。fill="outline "を使う場合、半径が大きいと表示が不 均一になることがある。 |
--border-style | ヘルパーテキスト、エラーテキスト、カウンターを使用する場合の入力下のボーダーのスタイル |
--border-width | ヘルパーテキスト、エラーテキスト、カウンターを使用する場合の入力下のボーダーの幅 |
--color | Inputのテキストの色 |
--highlight-color-focused | フォーカスされたときの入力のハイライトの色 |
--highlight-color-invalid | 入力が無効な場合のハイライトの色 |
--highlight-color-valid | 有効時の入力のハイライトの色 |
--highlight-height | 入力のハイライトの高さ。mdモードにのみ適用される。 |
--padding-bottom | InputのBottom Padding |
--padding-end | 入力の方向が左から右の場合はRight Padding、右から左の場合はLeft Paddingとなります。 |
--padding-start | 入力の方向が左から右の場合はLeft Padding、右から左の場合はRight Paddingとなります。 |
--padding-top | InputのTop Padding |
--placeholder-color | InputのPlaceholderテキストの色 |
--placeholder-font-style | InputのPlaceholderテキストのFont Style |
--placeholder-font-weight | InputのPlaceholderテキストのFont Weight |
--placeholder-opacity | InputのPlaceholderテキストの不透明度 |
| Name | Description |
|---|
end | 入力の後端に表示する内容。(実験的) |
label | 入力に関連付けるラベルテキスト。labelPlacement`プロパティを使用すると、入力に対してラベルを配置する位置を制御することができる。ラベルをカスタム HTML でレンダリングする必要がある場合に使用します。(EXPERIMENTAL) |
start | 入力の最先端に表示するコンテンツ。(実験的) |