Skip to content

Commit 6dcc66f

Browse files
committed
fix(docs/checkbox): finished documentation
1 parent c8c94fd commit 6dcc66f

File tree

3 files changed

+92
-35
lines changed

3 files changed

+92
-35
lines changed
Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
import { component$, useSignal, useStyles$ } from '@builder.io/qwik';
2+
import { Checkbox } from '@qwik-ui/headless';
3+
export default component$(() => {
4+
const initialVal1 = false;
5+
const controlledSig1 = useSignal(initialVal1);
6+
const initialVal2 = true;
7+
const controlledSig2 = useSignal(initialVal2);
8+
return (
9+
<>
10+
<div class="flex gap-8">
11+
<div class="flex flex-col gap-3">
12+
<Checkbox.Root
13+
bind:checked={controlledSig1}
14+
id="test"
15+
class="flex items-center gap-3 border-2 border-black p-2 "
16+
>
17+
<Checkbox.Indicator class="flex h-[25px] w-[25px] items-center justify-center bg-slate-600">
18+
19+
</Checkbox.Indicator>
20+
Toggle Value
21+
</Checkbox.Root>
22+
<p>The initial value was: {`${initialVal1}`}</p>
23+
<p>The current value is: {`${controlledSig1.value}`}</p>
24+
</div>
25+
<div class="flex flex-col gap-3">
26+
<Checkbox.Root
27+
bind:checked={controlledSig2}
28+
id="test"
29+
class="flex items-center gap-3 border-2 border-black p-2 "
30+
>
31+
<Checkbox.Indicator class="flex h-[25px] w-[25px] items-center justify-center bg-slate-600">
32+
33+
</Checkbox.Indicator>
34+
Toggle Value
35+
</Checkbox.Root>
36+
<p>The initial value was: {`${initialVal2}`}</p>
37+
<p>The current value is: {`${controlledSig2.value}`}</p>
38+
</div>
39+
</div>
40+
</>
41+
);
42+
});

apps/website/src/routes/docs/headless/checkbox/examples/controlled.tsx

Lines changed: 16 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,23 @@
1-
import { component$, useSignal, useStyles$ } from '@builder.io/qwik';
1+
import { component$, useSignal } from '@builder.io/qwik';
22
import { Checkbox } from '@qwik-ui/headless';
33
export default component$(() => {
4-
const controlledSig = useSignal(false);
4+
const initialVal1 = false;
5+
const controlledSig1 = useSignal(initialVal1);
56
return (
67
<>
7-
<div class="flex flex-col gap-3">
8-
<Checkbox.Root
9-
bind:checked={controlledSig}
10-
id="test"
11-
class="flex items-center gap-3 border-2 border-black p-2 "
12-
>
13-
<Checkbox.Indicator class="flex h-[25px] w-[25px] items-center justify-center bg-slate-600">
14-
15-
</Checkbox.Indicator>
16-
Toggle Signal
17-
</Checkbox.Root>
18-
<p>Your signal's value is: {`${controlledSig.value}`}</p>
8+
<div class="flex gap-8">
9+
<div class="flex flex-col gap-3">
10+
<Checkbox.Root
11+
bind:checked={controlledSig1}
12+
id="test"
13+
class="flex items-center gap-3 border-2 border-black p-2 "
14+
>
15+
<Checkbox.Indicator class="flex h-[25px] w-[25px] items-center justify-center bg-slate-600">
16+
17+
</Checkbox.Indicator>
18+
Toggle Value
19+
</Checkbox.Root>
20+
</div>
1921
</div>
2022
</>
2123
);

apps/website/src/routes/docs/headless/checkbox/index.mdx

Lines changed: 34 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -7,49 +7,43 @@ import { statusByComponent } from '~/_state/component-statuses';
77

88
<StatusBanner status={statusByComponent.headless.Select} />
99

10-
# Checkbox
10+
# Checkbox (Two-State)
1111

1212
Allows users to visually select an option by "checking" it.
1313

1414
<Showcase name="hero" />
15-
### Anatomy
15+
## Anatomy
1616

1717
<AnatomyTable
1818
propDescriptors={[
1919
{
2020
name: 'Checkbox.Root',
2121
description:
22-
'Defines the component boundary and exposes its internal logic; must wrap over all other parts',
22+
'Defines the component boundary and exposes its internal logic AND must wrap over all other parts',
2323
},
2424
{
2525
name: 'Checkbox.Indicator',
26-
description: 'Wrapper that automatically handles show & hide logic for you',
26+
description:
27+
'Wrapper that automatically shows its children when true and hides them when false',
2728
},
2829
]}
2930
/>
3031

31-
### API
32+
## Examples
3233

33-
<AnatomyTable
34-
propDescriptors={[
35-
{
36-
name: 'checkboxSig',
37-
description: 'Defined at the root; binds the value to a boolean signal',
38-
},
39-
{
40-
name: 'checklist',
41-
description:
42-
"Defined at the root; makes the checkbox be treated as a tri-state checkbox AND binds it's value over all other checkboxes inside a checklist",
43-
},
44-
]}
45-
/>
46-
### API examples #### Controlled Checkbox
34+
### Controlled Checkbox
35+
36+
You can bind the internal value of a checkbox to a user-defined signal:
4737

4838
<Showcase name="controlled" />
4939

50-
This example shows that you can pass down your own signal to handle the boolean logic. Note that the initial value of your signal will affect the initial value of the checkbox.
40+
Do keep in mind that the inital value of the signal WILL affect the initial value of the checkbox.
41+
42+
In the example below, the left checkbox was bindided to a signal with an inital value of false while the right checkbox was bindded to a signal with an inital falue of true.
43+
44+
<Showcase name="controlled-values" />
5145

52-
### Customization & Caveats
46+
## Customization & Caveats
5347

5448
The Checkbox is made from the ground up to be as customizable as possible.
5549

@@ -60,3 +54,22 @@ You can define your own CSS classes on every part of the component as if it were
6054
Due to the implementation of the Checkbox element being a div with the role of checkbox, any text present inside the Checkbox Root is interpreted as the checkbox label.
6155

6256
This also means that any text tag is stripped from its semantic meaning. In other words, passing an h1 tag is treated the same as passing a p tag: they are both treated as if you passed no tag at all. See [this](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/checkbox_role#all_descendants_are_presentational) section of MDN for a more detailed explenation.
57+
58+
## API
59+
60+
### Checkbox.Root
61+
62+
<AnatomyTable
63+
propDescriptors={[
64+
{
65+
name: 'bind:checked',
66+
description:
67+
'two-way data bind of the value of the checkbox to a user-defined signal',
68+
},
69+
{
70+
name: 'checklist',
71+
description:
72+
"when true makes the checkbox be treated as a tri-state checkbox AND binds it's value over all other checkboxes inside the checklist",
73+
},
74+
]}
75+
/>

0 commit comments

Comments
 (0)