メインコンテンツまでスキップ
バージョン: v8 (beta)

ion-checkbox

shadow

Checkboxを使用すると、一連のオプションから複数のオプションを選択できます。選択すると、チェックマークが付いた状態(checked)で表示されます。checkboxをクリックすると、 checked プロパティーが切り替わります。checked プロパティを設定して、プログラムで checked を切り替えることもできます。

基本的な使い方

Label Placement

開発者は labelPlacement プロパティを使用して、ラベルをコントロールに対してどのように配置するかを制御できます。このプロパティはフレックスボックスの flex-direction プロパティを反映しています。

Alignment

Developers can use the alignment property to control how the label and control are aligned on the cross axis. This property mirrors the flexbox align-items property.

注記

Stacked checkboxes can be aligned using the alignment property. This can be useful when the label and control need to be centered horizontally.

Justification

開発者は justify プロパティを使用して、ラベルとコントロールの行の詰め方を制御することができます。このプロパティはフレックスボックスの justify-content プロパティを反映しています。

注記

ion-itemは、 justify がどのように機能するかを強調するためにデモで使用されているだけです。 justify が正しく機能するために必須ではありません。

Indeterminate Checkboxes

テーマ

CSSカスタムプロパティ

Interfaces

CheckboxChangeEventDetail

interface CheckboxChangeEventDetail<T = any> {
value: T;
checked: boolean;
}

CheckboxCustomEvent

必須ではありませんが、このコンポーネントから発行される Ionic イベントでより強く型付けを行うために、CustomEvent インターフェースの代わりにこのインターフェースを使用することが可能です。

interface CheckboxCustomEvent<T = any> extends CustomEvent {
detail: CheckboxChangeEventDetail<T>;
target: HTMLIonCheckboxElement;
}

レガシーなチェックボックス構文からのマイグレーション

Ionic 7.0では、よりシンプルなチェックボックス構文が導入されました。この新しい構文は、チェックボックスの設定に必要な定型文を減らし、アクセシビリティの問題を解決し、開発者のエクスペリエンスを向上させます。

開発者は、この移行を一度に1つのチェックボックスずつ実行することができます。開発者はレガシー構文を使い続けることができますが、できるだけ早く移行することをお勧めします。

最新の構文の使い方

最新の構文を使用するには、ion-label を削除して、 ion-checkbox の中に直接ラベルを渡す必要があります。ラベルの配置は ion-checkboxlabelPlacement プロパティを使用して設定することができる。ラベルとコントロールの行の詰め方は、ion-checkboxjustify プロパティを使用して制御することができます。

<!-- Basic -->

<!-- Before -->
<ion-item>
<ion-label>Checkbox Label</ion-label>
<ion-checkbox></ion-checkbox>
</ion-item>

<!-- After -->
<ion-item>
<ion-checkbox>Checkbox Label</ion-checkbox>
</ion-item>

<!-- Fixed Labels -->

<!-- Before -->
<ion-item>
<ion-label position="fixed">Checkbox Label</ion-label>
<ion-checkbox></ion-checkbox>
</ion-item>

<!-- After -->
<ion-item>
<ion-checkbox label-placement="fixed">Checkbox Label</ion-checkbox>
</ion-item>

<!-- Checkbox at the start of line, Label at the end of line -->

<!-- Before -->
<ion-item>
<ion-label slot="end">Checkbox Label</ion-label>
<ion-checkbox></ion-checkbox>
</ion-item>

<!-- After -->
<ion-item>
<ion-checkbox label-placement="end">Checkbox Label</ion-checkbox>
</ion-item>
注記

Ionic の過去のバージョンでは、ion-checkbox が正しく機能するために ion-item が必要でした。Ionic 7.0 からは、ion-checkboxion-item の中で、そのアイテムが ion-list に配置される場合にのみ使用されます。また、ion-checkboxが正しく機能するためには、ion-itemはもはや必須ではありません。

レガシーな構文の使い方

Ionicは、アプリが最新のチェックボックス構文を使用しているかどうかをヒューリスティックに検出します。場合によっては、レガシーな構文を使い続けることが望ましい場合もあります。開発者は ion-checkboxlegacy プロパティを true に設定することで、そのチェックボックスのインスタンスがレガシー構文を使用するように強制できます。

プロパティ

alignment

DescriptionHow to control the alignment of the checkbox and label on the cross axis. "start": The label and control will appear on the left of the cross axis in LTR, and on the right side in RTL. "center": The label and control will appear at the center of the cross axis in both LTR and RTL.
Attributealignment
Type"center" | "start"
Default'center'

checked

DescriptionIf true, the checkbox is selected.
Attributechecked
Typeboolean
Defaultfalse

color

DescriptionThe color to use from your application's color palette. Default options are: "primary", "secondary", "tertiary", "success", "warning", "danger", "light", "medium", and "dark". For more information on colors, see theming.
Attributecolor
Type"danger" | "dark" | "light" | "medium" | "primary" | "secondary" | "success" | "tertiary" | "warning" | string | undefined
Defaultundefined

disabled

DescriptionIf true, the user cannot interact with the checkbox.
Attributedisabled
Typeboolean
Defaultfalse

indeterminate

DescriptionIf true, the checkbox will visually appear as indeterminate.
Attributeindeterminate
Typeboolean
Defaultfalse

justify

DescriptionHow to pack the label and checkbox within a line. "start": The label and checkbox will appear on the left in LTR and on the right in RTL. "end": The label and checkbox will appear on the right in LTR and on the left in RTL. "space-between": The label and checkbox will appear on opposite ends of the line with space between the two elements.
Attributejustify
Type"end" | "space-between" | "start"
Default'space-between'

labelPlacement

DescriptionWhere to place the label relative to the checkbox. "start": The label will appear to the left of the checkbox in LTR and to the right in RTL. "end": The label will appear to the right of the checkbox in LTR and to the left in RTL. "fixed": The label has the same behavior as "start" except it also has a fixed width. Long text will be truncated with ellipses ("..."). "stacked": The label will appear above the checkbox regardless of the direction. The alignment of the label can be controlled with the alignment property.
Attributelabel-placement
Type"end" | "fixed" | "stacked" | "start"
Default'start'

legacy

DescriptionSet the legacy property to true to forcibly use the legacy form control markup. Ionic will only opt checkboxes in to the modern form markup when they are using either the aria-label attribute or have text in the default slot. As a result, the legacy property should only be used as an escape hatch when you want to avoid this automatic opt-in behavior.

Note that this property will be removed in an upcoming major release of Ionic, and all form components will be opted-in to using the modern form markup.
Attributelegacy
Typeboolean | undefined
Defaultundefined

mode

DescriptionThe mode determines which platform styles to use.
Attributemode
Type"ios" | "md"
Defaultundefined

name

DescriptionThe name of the control, which is submitted with the form data.
Attributename
Typestring
Defaultthis.inputId

value

DescriptionThe value of the checkbox does not mean if it's checked or not, use the checked property for that.

The value of a checkbox is analogous to the value of an <input type="checkbox">, it's only used when the checkbox participates in a native <form>.
Attributevalue
Typeany
Default'on'

イベント

NameDescriptionBubbles
ionBlurEmitted when the checkbox loses focus.true
ionChangeEmitted when the checked property has changed as a result of a user action such as a click. This event will not emit when programmatically setting the checked property.true
ionFocusEmitted when the checkbox has focus.true

メソッド

No public methods available for this component.

CSS Shadow Parts

NameDescription
containerThe container for the checkbox mark.
labelThe label text describing the checkbox.
markThe checkmark used to indicate the checked state.

CSSカスタムプロパティ

NameDescription
--border-colorBorder color of the checkbox icon
--border-color-checkedBorder color of the checkbox icon when checked
--border-radiusBorder radius of the checkbox icon
--border-styleBorder style of the checkbox icon
--border-widthBorder width of the checkbox icon
--checkbox-backgroundBackground of the checkbox icon
--checkbox-background-checkedBackground of the checkbox icon when checked
--checkmark-colorColor of the checkbox checkmark when checked
--checkmark-widthStroke width of the checkbox checkmark
--sizeSize of the checkbox icon
--transitionTransition of the checkbox icon

Slots

NameDescription
``The label text to associate with the checkbox. Use the "labelPlacement" property to control where the label is placed relative to the checkbox.