Checkbox
チェックされている、チェックされていない、または不確定なコントロール。
CheckboxはCheckbox WAI-ARIAデザインパターンに準拠しています。
import { component$, useStyles$ } from '@builder.io/qwik';
import { Checkbox } from '@leve-ui/checkbox';
import { LuCheck } from '@qwikest/icons/lucide';
import styles from './default.css?inline';
export default component$(() => {
useStyles$(styles);
return (
<Checkbox.Root class="checkbox-default-root">
<Checkbox.Control class="checkbox-default-control">
<Checkbox.Indicator class="checkbox-default-indicator">
<LuCheck class="checkbox-default-icon" aria-hidden="true" />
</Checkbox.Indicator>
</Checkbox.Control>
<Checkbox.Label class="checkbox-default-label">Accept terms and conditions</Checkbox.Label>
<Checkbox.HiddenInput />
</Checkbox.Root>
);
});.checkbox-default-root {
/* HiddenInput is absolutely positioned inside Root */
position: relative;
display: inline-flex;
align-items: center;
gap: 10px;
font-family: inherit;
}
.checkbox-default-control {
display: inline-flex;
align-items: center;
justify-content: center;
width: 18px;
height: 18px;
padding: 0;
border: 1px solid light-dark(#cbd5e1, #ffffff3d);
border-radius: 4px;
background: light-dark(#ffffff, #1b2045);
cursor: pointer;
}
.checkbox-default-control[data-state="checked"] {
background: #009dfd;
border-color: #009dfd;
}
.checkbox-default-control:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
.checkbox-default-control:disabled {
opacity: 0.5;
cursor: not-allowed;
}
/* The indicator is always rendered; show it only when checked */
.checkbox-default-indicator {
display: none;
color: #ffffff;
}
.checkbox-default-indicator[data-state="checked"] {
display: inline-flex;
}
.checkbox-default-icon {
width: 12px;
height: 12px;
}
.checkbox-default-label {
font-size: 14px;
color: light-dark(#0f172a, #ffffff);
cursor: pointer;
}インストール#
個別のパッケージをインストールするか、@leve-ui/coreを使用してすべてのコンポーネントを一度に取得します。
pnpm add @leve-ui/checkboxnpm install @leve-ui/checkboxyarn add @leve-ui/checkboxbun add @leve-ui/checkboxpnpm add @leve-ui/corenpm install @leve-ui/coreyarn add @leve-ui/corebun add @leve-ui/core構造#
import { Checkbox } from '@leve-ui/checkbox'; // or '@leve-ui/core'
<Checkbox.Root>
<Checkbox.Control>
<Checkbox.Indicator />
</Checkbox.Control>
<Checkbox.Label />
<Checkbox.HiddenInput />
</Checkbox.Root>
| パーツ | 要素 | 説明 |
|---|---|---|
Checkbox.Root | <div> | 各パーツをラップし、チェック状態を保持します。非インタラクティブです。 |
Checkbox.Control | <button> | チェックボックス本体(role="checkbox"付き)。 |
Checkbox.Indicator | <span> | チェックマークやその他のアイコンを保持します。常にレンダリングされます。 |
Checkbox.Label | <label> | ラベル。クリックするとチェックボックスが切り替わります。 |
Checkbox.HiddenInput | <input type="checkbox"> | 省略可能。ネイティブの<form>で状態を送信します。 |
例#
Checked#
defaultCheckedで初期状態を設定します。
import { component$, useStyles$ } from '@builder.io/qwik';
import { Checkbox } from '@leve-ui/checkbox';
import { LuCheck } from '@qwikest/icons/lucide';
import styles from './checked.css?inline';
export default component$(() => {
useStyles$(styles);
return (
<Checkbox.Root defaultChecked={true} class="checkbox-checked-root">
<Checkbox.Control class="checkbox-checked-control">
<Checkbox.Indicator class="checkbox-checked-indicator">
<LuCheck class="checkbox-checked-icon" aria-hidden="true" />
</Checkbox.Indicator>
</Checkbox.Control>
<Checkbox.Label class="checkbox-checked-label">Subscribe to newsletter</Checkbox.Label>
<Checkbox.HiddenInput />
</Checkbox.Root>
);
});.checkbox-checked-root {
/* HiddenInput is absolutely positioned inside Root */
position: relative;
display: inline-flex;
align-items: center;
gap: 10px;
font-family: inherit;
}
.checkbox-checked-control {
display: inline-flex;
align-items: center;
justify-content: center;
width: 18px;
height: 18px;
padding: 0;
border: 1px solid light-dark(#cbd5e1, #ffffff3d);
border-radius: 4px;
background: light-dark(#ffffff, #1b2045);
cursor: pointer;
}
.checkbox-checked-control[data-state="checked"] {
background: #009dfd;
border-color: #009dfd;
}
.checkbox-checked-control:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
.checkbox-checked-control:disabled {
opacity: 0.5;
cursor: not-allowed;
}
/* The indicator is always rendered; show it only when checked */
.checkbox-checked-indicator {
display: none;
color: #ffffff;
}
.checkbox-checked-indicator[data-state="checked"] {
display: inline-flex;
}
.checkbox-checked-icon {
width: 12px;
height: 12px;
}
.checkbox-checked-label {
font-size: 14px;
color: light-dark(#0f172a, #ffffff);
cursor: pointer;
}Disabled#
Rootのdisabledはチェックボックスを無効化します。
import { component$, useStyles$ } from '@builder.io/qwik';
import { Checkbox } from '@leve-ui/checkbox';
import { LuCheck } from '@qwikest/icons/lucide';
import styles from './disabled.css?inline';
export default component$(() => {
useStyles$(styles);
return (
<Checkbox.Root disabled class="checkbox-disabled-root">
<Checkbox.Control class="checkbox-disabled-control">
<Checkbox.Indicator class="checkbox-disabled-indicator">
<LuCheck class="checkbox-disabled-icon" aria-hidden="true" />
</Checkbox.Indicator>
</Checkbox.Control>
<Checkbox.Label class="checkbox-disabled-label">Disabled option</Checkbox.Label>
<Checkbox.HiddenInput />
</Checkbox.Root>
);
});.checkbox-disabled-root {
font-family: inherit;
/* HiddenInput is absolutely positioned inside Root */
position: relative;
display: inline-flex;
align-items: center;
gap: 10px;
}
.checkbox-disabled-control {
display: inline-flex;
align-items: center;
justify-content: center;
width: 18px;
height: 18px;
padding: 0;
border: 1px solid light-dark(#cbd5e1, #ffffff3d);
border-radius: 4px;
background: light-dark(#ffffff, #1b2045);
cursor: pointer;
}
.checkbox-disabled-control[data-state="checked"] {
background: #009dfd;
border-color: #009dfd;
}
.checkbox-disabled-control:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
.checkbox-disabled-control:disabled {
opacity: 0.5;
cursor: not-allowed;
}
/* The indicator is always rendered; show it only when checked */
.checkbox-disabled-indicator {
display: none;
color: #ffffff;
}
.checkbox-disabled-indicator[data-state="checked"] {
display: inline-flex;
}
.checkbox-disabled-icon {
width: 12px;
height: 12px;
}
.checkbox-disabled-label {
font-size: 14px;
color: light-dark(#0f172a, #ffffff);
cursor: pointer;
}
.checkbox-disabled-label[data-disabled] {
opacity: 0.5;
cursor: not-allowed;
}Indeterminate#
「すべて選択」チェックボックスなどでは、チェック状態を"indeterminate"にできます。このデモでは、bind:checkedとonCheckedChange$を使用して状態を制御しています。
import { $, component$, useComputed$, useSignal, useStyles$, useTask$ } from '@builder.io/qwik';
import { Checkbox, type CheckboxCheckedState } from '@leve-ui/checkbox';
import { LuCheck, LuMinus } from '@qwikest/icons/lucide';
import styles from './indeterminate.css?inline';
export default component$(() => {
useStyles$(styles);
const child1 = useSignal(true);
const child2 = useSignal(false);
const child3 = useSignal(false);
const parent = useSignal<CheckboxCheckedState>('indeterminate');
// Synchronize parent state based on child values
useTask$(({ track }) => {
const c1 = track(() => child1.value);
const c2 = track(() => child2.value);
const c3 = track(() => child3.value);
const all = c1 && c2 && c3;
const none = !c1 && !c2 && !c3;
if (all) {
parent.value = true;
} else if (none) {
parent.value = false;
} else {
parent.value = 'indeterminate';
}
});
const selectedCount = useComputed$(() => {
return [child1.value, child2.value, child3.value].filter(Boolean).length;
});
const handleParentChange$ = $((next: CheckboxCheckedState) => {
const target = next === true;
child1.value = target;
child2.value = target;
child3.value = target;
});
return (
<div class="checkbox-indeterminate-group">
<Checkbox.Root
bind:checked={parent}
onCheckedChange$={handleParentChange$}
class="checkbox-indeterminate-root"
>
<Checkbox.Control class="checkbox-indeterminate-control">
<Checkbox.Indicator class="checkbox-indeterminate-indicator">
<LuCheck class="checkbox-indeterminate-icon-check" aria-hidden="true" />
<LuMinus class="checkbox-indeterminate-icon-indeterminate" aria-hidden="true" />
</Checkbox.Indicator>
</Checkbox.Control>
<Checkbox.Label class="checkbox-indeterminate-label">Select all ingredients</Checkbox.Label>
<span class="checkbox-indeterminate-count">({selectedCount.value} of 3 selected)</span>
<Checkbox.HiddenInput />
</Checkbox.Root>
<div class="checkbox-indeterminate-group-children">
<Checkbox.Root bind:checked={child1} class="checkbox-indeterminate-root">
<Checkbox.Control class="checkbox-indeterminate-control">
<Checkbox.Indicator class="checkbox-indeterminate-indicator">
<LuCheck class="checkbox-indeterminate-icon-check" aria-hidden="true" />
</Checkbox.Indicator>
</Checkbox.Control>
<Checkbox.Label class="checkbox-indeterminate-label">Lettuce</Checkbox.Label>
<Checkbox.HiddenInput />
</Checkbox.Root>
<Checkbox.Root bind:checked={child2} class="checkbox-indeterminate-root">
<Checkbox.Control class="checkbox-indeterminate-control">
<Checkbox.Indicator class="checkbox-indeterminate-indicator">
<LuCheck class="checkbox-indeterminate-icon-check" aria-hidden="true" />
</Checkbox.Indicator>
</Checkbox.Control>
<Checkbox.Label class="checkbox-indeterminate-label">Tomato</Checkbox.Label>
<Checkbox.HiddenInput />
</Checkbox.Root>
<Checkbox.Root bind:checked={child3} class="checkbox-indeterminate-root">
<Checkbox.Control class="checkbox-indeterminate-control">
<Checkbox.Indicator class="checkbox-indeterminate-indicator">
<LuCheck class="checkbox-indeterminate-icon-check" aria-hidden="true" />
</Checkbox.Indicator>
</Checkbox.Control>
<Checkbox.Label class="checkbox-indeterminate-label">Cheese</Checkbox.Label>
<Checkbox.HiddenInput />
</Checkbox.Root>
</div>
</div>
);
});.checkbox-indeterminate-group {
display: flex;
flex-direction: column;
gap: 12px;
font-family: inherit;
}
.checkbox-indeterminate-group-children {
display: flex;
flex-direction: column;
gap: 12px;
padding-left: 28px;
}
.checkbox-indeterminate-root {
/* HiddenInput is absolutely positioned inside Root */
position: relative;
display: inline-flex;
align-items: center;
gap: 10px;
}
.checkbox-indeterminate-control {
display: inline-flex;
align-items: center;
justify-content: center;
width: 18px;
height: 18px;
padding: 0;
border: 1px solid light-dark(#cbd5e1, #ffffff3d);
border-radius: 4px;
background: light-dark(#ffffff, #1b2045);
cursor: pointer;
}
.checkbox-indeterminate-control[data-state="checked"],
.checkbox-indeterminate-control[data-state="indeterminate"] {
background: #009dfd;
border-color: #009dfd;
}
.checkbox-indeterminate-control:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
/* The indicator is always rendered; show it only when checked or indeterminate */
.checkbox-indeterminate-indicator {
display: none;
color: #ffffff;
}
.checkbox-indeterminate-indicator[data-state="checked"],
.checkbox-indeterminate-indicator[data-state="indeterminate"] {
display: inline-flex;
}
.checkbox-indeterminate-icon-check,
.checkbox-indeterminate-icon-indeterminate {
display: none;
width: 12px;
height: 12px;
}
/* Check icon when checked, minus icon when indeterminate */
.checkbox-indeterminate-indicator[data-state="checked"] .checkbox-indeterminate-icon-check,
.checkbox-indeterminate-indicator[data-state="indeterminate"]
.checkbox-indeterminate-icon-indeterminate {
display: block;
}
.checkbox-indeterminate-label {
font-size: 14px;
color: light-dark(#0f172a, #ffffff);
cursor: pointer;
}
.checkbox-indeterminate-count {
font-size: 13px;
color: light-dark(#475569, #c9ddf0);
}Fieldと併用#
Field.Root内では、Checkbox.Labelの代わりにField.Labelを使用してください。FieldがID、説明、およびdisabled/required/invalid状態を提供します。
import { component$, useStyles$ } from '@builder.io/qwik';
import { Checkbox } from '@leve-ui/checkbox';
import { Field } from '@leve-ui/field';
import { LuCheck } from '@qwikest/icons/lucide';
import styles from './with-field.css?inline';
export default component$(() => {
useStyles$(styles);
return (
<Field.Root hasDescription class="checkbox-with-field-field">
<div class="checkbox-with-field-row">
<Checkbox.Root class="checkbox-with-field-root">
<Checkbox.Control class="checkbox-with-field-control">
<Checkbox.Indicator class="checkbox-with-field-indicator">
<LuCheck class="checkbox-with-field-icon" aria-hidden="true" />
</Checkbox.Indicator>
</Checkbox.Control>
<Checkbox.HiddenInput />
</Checkbox.Root>
<Field.Label class="checkbox-with-field-label">Remember me</Field.Label>
</div>
<Field.Description class="checkbox-with-field-description">
Save your session on this device for 30 days.
</Field.Description>
</Field.Root>
);
});.checkbox-with-field-field {
display: flex;
flex-direction: column;
gap: 6px;
width: 280px;
font-family: inherit;
}
.checkbox-with-field-row {
display: flex;
align-items: center;
gap: 10px;
}
.checkbox-with-field-root {
/* HiddenInput is absolutely positioned inside Root */
position: relative;
display: inline-flex;
align-items: center;
gap: 10px;
}
.checkbox-with-field-control {
display: inline-flex;
align-items: center;
justify-content: center;
width: 18px;
height: 18px;
padding: 0;
border: 1px solid light-dark(#cbd5e1, #ffffff3d);
border-radius: 4px;
background: light-dark(#ffffff, #1b2045);
cursor: pointer;
}
.checkbox-with-field-control[data-state="checked"] {
background: #009dfd;
border-color: #009dfd;
}
.checkbox-with-field-control:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
.checkbox-with-field-control:disabled {
opacity: 0.5;
cursor: not-allowed;
}
/* The indicator is always rendered; show it only when checked */
.checkbox-with-field-indicator {
display: none;
color: #ffffff;
}
.checkbox-with-field-indicator[data-state="checked"] {
display: inline-flex;
}
.checkbox-with-field-icon {
width: 12px;
height: 12px;
}
.checkbox-with-field-label {
font-size: 14px;
font-weight: 500;
color: light-dark(#0f172a, #ffffff);
cursor: pointer;
}
/* Indented to line up with the label text (control 18px + gap 10px) */
.checkbox-with-field-description {
margin: 0;
padding-left: 28px;
font-size: 13px;
color: light-dark(#475569, #c9ddf0);
}Formと併用#
ネイティブの<form>で状態を送信するには、nameとvalueを指定してCheckbox.HiddenInputを追加します。
import { $, component$, useSignal, useStyles$ } from '@builder.io/qwik';
import { Checkbox } from '@leve-ui/checkbox';
import { LuCheck } from '@qwikest/icons/lucide';
import styles from './with-form.css?inline';
export default component$(() => {
useStyles$(styles);
const submittedData = useSignal('');
const handleSubmit$ = $((_event: unknown, form: HTMLFormElement) => {
const formData = new FormData(form);
submittedData.value = JSON.stringify(Object.fromEntries(formData));
});
return (
<form class="checkbox-with-form-form" preventdefault:submit onSubmit$={handleSubmit$}>
<Checkbox.Root class="checkbox-with-form-root">
<Checkbox.Control class="checkbox-with-form-control">
<Checkbox.Indicator class="checkbox-with-form-indicator">
<LuCheck class="checkbox-with-form-icon" aria-hidden="true" />
</Checkbox.Indicator>
</Checkbox.Control>
<Checkbox.Label class="checkbox-with-form-label">Agree to marketing emails</Checkbox.Label>
<Checkbox.HiddenInput name="marketing" value="subscribed" />
</Checkbox.Root>
<button type="submit" class="checkbox-with-form-submit">
Submit
</button>
<output class="checkbox-with-form-output">{submittedData.value}</output>
</form>
);
});.checkbox-with-form-root {
/* HiddenInput is absolutely positioned inside Root */
position: relative;
display: inline-flex;
align-items: center;
gap: 10px;
}
.checkbox-with-form-control {
display: inline-flex;
align-items: center;
justify-content: center;
width: 18px;
height: 18px;
padding: 0;
border: 1px solid light-dark(#cbd5e1, #ffffff3d);
border-radius: 4px;
background: light-dark(#ffffff, #1b2045);
cursor: pointer;
}
.checkbox-with-form-control[data-state="checked"] {
background: #009dfd;
border-color: #009dfd;
}
.checkbox-with-form-control:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
.checkbox-with-form-control:disabled {
opacity: 0.5;
cursor: not-allowed;
}
/* The indicator is always rendered; show it only when checked */
.checkbox-with-form-indicator {
display: none;
color: #ffffff;
}
.checkbox-with-form-indicator[data-state="checked"] {
display: inline-flex;
}
.checkbox-with-form-icon {
width: 12px;
height: 12px;
}
.checkbox-with-form-label {
font-size: 14px;
color: light-dark(#0f172a, #ffffff);
cursor: pointer;
}
.checkbox-with-form-form {
display: flex;
flex-direction: column;
align-items: flex-start;
gap: 12px;
font-family: inherit;
}
.checkbox-with-form-submit {
height: 32px;
padding: 0 12px;
border: none;
border-radius: 6px;
background: #009dfd;
color: #ffffff;
font: inherit;
font-size: 13px;
font-weight: 500;
cursor: pointer;
}
.checkbox-with-form-submit:hover {
background: #006ce9;
}
.checkbox-with-form-submit:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
.checkbox-with-form-output {
margin: 0;
font-size: 13px;
color: light-dark(#475569, #c9ddf0);
}APIリファレンス#
Root#
| Prop | デフォルト | 型 |
|---|---|---|
| ids | – | { control?: string; label?: string } パーツの要素IDをオーバーライドします。Fieldの外でのみ使用されます。 |
| defaultChecked | false | boolean | 'indeterminate' 初期のチェック状態(非制御)。 |
| bind:checked | – | Signal<boolean | 'indeterminate'> チェック状態を保持するシグナル(制御)。 |
| onCheckedChange$ | – | QRL<(checked: boolean | 'indeterminate') => void> ユーザーがチェック状態を変更したときに呼び出されます。 |
| disabled | false | boolean チェックボックスを無効化します。Fieldの内部では、Fieldの |
| required | false | boolean チェックボックスを必須としてマークします。Fieldの内部では、Fieldの |
すべての<div>属性も受け入れます。
| データ属性 | 値 |
|---|---|
data-leve-checkbox | 常に存在 |
data-state | "checked" | "unchecked" | "indeterminate" |
data-disabled | 無効時に存在 |
チェック状態は、defaultCheckedによる非制御、またはbind:checkedによる制御が可能です。ユーザーが変更するとonCheckedChange$が呼び出されます。"indeterminate"のチェックボックスを切り替えるとチェック状態になります。
Fieldの内部では、IDはFieldから提供され、idsは無視されます(ADR 0024)。
Control#
独自のpropはありません。 すべての<button>属性を受け入れます。
| データ属性 | 値 |
|---|---|
data-leve-checkbox-control | 常に存在 |
data-state | "checked" | "unchecked" | "indeterminate" |
data-disabled | 無効時に存在 |
data-invalid | Fieldが無効な場合に存在 |
Indicator#
独自のpropはありません。 すべての<span>属性を受け入れます。
| データ属性 | 値 |
|---|---|
data-leve-checkbox-indicator | 常に存在 |
data-state | "checked" | "unchecked" | "indeterminate" |
data-disabled | 無効時に存在 |
インジケーターは常にレンダリングされます。[data-leve-checkbox-indicator][data-state="unchecked"]などのCSSを使用してアイコンを表示または非表示にします。
Label#
独自のpropはありません。 すべての<label>属性を受け入れます。
| データ属性 | 値 |
|---|---|
data-leve-checkbox-label | 常に存在 |
data-state | "checked" | "unchecked" | "indeterminate" |
data-disabled | 無効時に存在 |
HiddenInput#
独自のpropはありません。 すべての<input>属性を受け入れます。
| データ属性 | 値 |
|---|---|
data-leve-checkbox-hidden-input | 常に存在 |
data-state | "checked" | "unchecked" | "indeterminate" |
data-disabled | 無効時に存在 |
非表示のinputはchecked、required、disabledの状態に追従するため、ネイティブのフォーム送信とrequiredバリデーションが機能します(ADR 0026)。インラインスタイルで絶対配置されるため、Checkbox.Rootにposition: relativeを指定してください。
アクセシビリティ#
Checkbox WAI-ARIAデザインパターンに準拠しています。
- チェックボックスの名前付けには、
Checkbox.Label、Field.Label、またはCheckbox.Controlのaria-label/aria-labelledbyを使用します。 Checkbox.Controlはrole="checkbox"とaria-checked("true"、"false"または"mixed")をレンダリングし、必須の場合はaria-requiredもレンダリングします。Field内ではaria-describedbyとaria-invalidもレンダリングします。- 状態によってラベルのテキストを変更しないでください。状態は
aria-checkedによって伝達されます。 Checkbox.IndicatorとCheckbox.HiddenInputはaria-hidden="true"によって支援技術から隠されます。
キーボード操作#
| キー | 説明 |
|---|---|
Space | チェックボックスをオンまたはオフにします。 |
Enter | チェックボックスをオンまたはオフにします。 |