Checkbox (Two-State)
Allows users to visually select an option by checking it.
import { component$, useSignal, useStyles$ } from '@builder.io/qwik';
import { Checkbox } from '@qwik-ui/headless';
export default component$(() => {
return (
<>
<Checkbox.Root id="test" class="flex items-center gap-3 border-2 border-black p-2 ">
<Checkbox.Indicator class="flex h-[25px] w-[25px] items-center justify-center bg-slate-600">
✅
</Checkbox.Indicator>
I have read the README
</Checkbox.Root>
</>
);
});
Anatomy
Component | Description |
Checkbox.Root | Defines the component boundary and exposes its internal logic AND must wrap over all other parts |
Checkbox.Indicator | Wrapper that automatically shows its children when true and hides them when false |
Examples
Controlled Checkbox
To add reactive state, use the bind:checked
prop on the <Checkbox.Root />
component.
import { component$, useSignal } from '@builder.io/qwik';
import { Checkbox } from '@qwik-ui/headless';
export default component$(() => {
const initialVal1 = false;
const controlledSig1 = useSignal(initialVal1);
return (
<>
<div class="flex gap-8">
<div class="flex flex-col gap-3">
<Checkbox.Root
bind:checked={controlledSig1}
id="test"
class="flex items-center gap-3 border-2 border-black p-2 "
>
<Checkbox.Indicator class="flex h-[25px] w-[25px] items-center justify-center bg-slate-600">
✅
</Checkbox.Indicator>
Toggle Value
</Checkbox.Root>
</div>
</div>
</>
);
});
In the example below, the left checkbox starts as false, while the right checkbox starts as true.
The initial value was: false
The current value is: false
The initial value was: true
The current value is: true
import { component$, useSignal, useStyles$ } from '@builder.io/qwik';
import { Checkbox } from '@qwik-ui/headless';
export default component$(() => {
const initialVal1 = false;
const controlledSig1 = useSignal(initialVal1);
const initialVal2 = true;
const controlledSig2 = useSignal(initialVal2);
return (
<>
<div class="flex gap-8">
<div class="flex flex-col gap-3">
<Checkbox.Root
bind:checked={controlledSig1}
id="test"
class="flex items-center gap-3 border-2 border-black p-2 "
>
<Checkbox.Indicator class="flex h-[25px] w-[25px] items-center justify-center bg-slate-600">
✅
</Checkbox.Indicator>
Toggle Value
</Checkbox.Root>
<p>The initial value was: {`${initialVal1}`}</p>
<p>The current value is: {`${controlledSig1.value}`}</p>
</div>
<div class="flex flex-col gap-3">
<Checkbox.Root
bind:checked={controlledSig2}
id="test"
class="flex items-center gap-3 border-2 border-black p-2 "
>
<Checkbox.Indicator class="flex h-[25px] w-[25px] items-center justify-center bg-slate-600">
✅
</Checkbox.Indicator>
Toggle Value
</Checkbox.Root>
<p>The initial value was: {`${initialVal2}`}</p>
<p>The current value is: {`${controlledSig2.value}`}</p>
</div>
</div>
</>
);
});
Customization & Caveats
You can apply CSS classes to any part of the component. Any valid HTML can be used as an icon, but children of the Checkbox Indicator are removed from the accessibility tree to prevent them from being added to the Checkbox Label.
Automatic Labeling
The Checkbox element is a div with the role of checkbox, so any text inside the Checkbox Root is interpreted as the checkbox label.
Text tags lose their semantic meaning. For example, an h1 tag is treated the same as a p tag. See this MDN section for more details.
API
Checkbox.Root
Component | Description |
bind:checked | Two-way data binding of the checkbox value to a user-defined signal |
checklist | When true, treats the checkbox as a tri-state and binds its value to all other checkboxes in the checklist |