Skip to content

Commit af483c8

Browse files
athphaneathphane
committed
docs: document checkbox component
1 parent 4418f83 commit af483c8

1 file changed

Lines changed: 159 additions & 0 deletions

File tree

‎docs/basic-usage/checkbox.md‎

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
---
2+
title: Checkbox
3+
sidebar_position: 2.5
4+
---
5+
6+
The `checkbox` component renders a checkbox with a label, model binding, and validation errors. It supports Bootstrap 5 and Material Admin 2.6.
7+
8+
## Basic Usage
9+
10+
Only the `name` attribute is required. The label is generated from the name, so `send_notifications` becomes "Send Notifications".
11+
12+
```html
13+
<x-forms::checkbox name="send_notifications" />
14+
15+
<x-forms::checkbox name="send_notifications" label="Send me notifications" />
16+
```
17+
18+
When checked, the checkbox submits its `value`, which defaults to `1`. An unchecked checkbox does not submit a value. The component does not add a hidden input for the unchecked state; handle missing values in your request handling.
19+
20+
## Values and Checked State
21+
22+
Use `value` to set the value submitted when checked, and `default` to set the initial checked state.
23+
24+
```html
25+
<x-forms::checkbox name="newsletter" value="yes" :default="true" />
26+
```
27+
28+
This checkbox starts checked and submits `newsletter=yes`. Use Blade's `:` syntax to pass a boolean, such as `:default="false"`, rather than the string `default="false"`.
29+
30+
The component determines its checked state in this order:
31+
32+
1. **Old input:** After a submission with flashed input, the checkbox is checked when its `value` appears in the old input for its name. Missing or empty old input leaves it unchecked, even if a model or default would otherwise check it.
33+
2. **Bound value:** Without old input, an array or an `Arrayable` value, such as a collection, checks the checkbox when it contains the checkbox's `value`. A scalar bound value determines the checked state by its boolean value.
34+
3. **Default:** When the bound value is `null`, `default` determines the checked state. It defaults to `false`.
35+
36+
A scalar bound value is not compared to `value`. For a single checkbox, bind a boolean or a `0`/`1` attribute; for a group of choices, bind an array of selected values.
37+
38+
### Model Binding
39+
40+
Bind a model or array to a single checkbox, or inherit the model from the surrounding form:
41+
42+
```html
43+
<x-forms::checkbox name="send_notifications" :model="$user" />
44+
45+
<x-forms::form :model="$user">
46+
<x-forms::checkbox name="send_notifications" />
47+
</x-forms::form>
48+
```
49+
50+
These examples use `$user->send_notifications` to determine whether the checkbox is checked. A bound `false` value takes precedence over `:default="true"`.
51+
52+
To ignore the surrounding model for a checkbox, pass `:model="false"`:
53+
54+
```html
55+
<x-forms::checkbox name="newsletter" :model="false" :default="true" />
56+
```
57+
58+
See [Model Binding and Default Values](./model-binding.md) for other binding methods. For checkboxes, `value` is always the submitted value; the checked-state rules above determine selection.
59+
60+
### Checkbox Groups
61+
62+
Use an array-style name and a different `value` for each choice. Give each checkbox a unique `id`, because the generated ID depends on the name and would otherwise be shared by every checkbox in the group.
63+
64+
```html
65+
<x-forms::form :model="['channels' => ['email']]">
66+
<x-forms::checkbox
67+
name="channels[]"
68+
id="channels-email"
69+
label="Email"
70+
value="email"
71+
/>
72+
73+
<x-forms::checkbox
74+
name="channels[]"
75+
id="channels-sms"
76+
label="SMS"
77+
value="sms"
78+
/>
79+
</x-forms::form>
80+
```
81+
82+
Here, Email starts checked and SMS starts unchecked. Selecting both submits `channels` as an array containing `email` and `sms`. Old input for `channels` restores each choice after a submission.
83+
84+
## Labels and Layout
85+
86+
Use the default slot for a label containing HTML:
87+
88+
```html
89+
<x-forms::checkbox name="accept_terms" required>
90+
I agree to the <a href="/terms">terms and conditions</a>.
91+
</x-forms::checkbox>
92+
```
93+
94+
For a horizontal form layout, add `inline`. The field label appears in a separate column; the label beside the checkbox is blank unless you supply slot content.
95+
96+
```html
97+
<x-forms::checkbox
98+
name="send_notifications"
99+
label="Notifications"
100+
inline
101+
inline-label-class="col-sm-4 col-form-label"
102+
inline-input-class="col-sm-8"
103+
>
104+
Send me email notifications
105+
</x-forms::checkbox>
106+
```
107+
108+
Default column classes come from the selected framework's `inline-label-class` and `inline-input-class` configuration.
109+
110+
Set `:show-label="false"` to remove the wrapping form group. The label beside the checkbox is still rendered.
111+
112+
## Help Text and Validation
113+
114+
Add helper text with the named `help` slot:
115+
116+
```html
117+
<x-forms::checkbox name="send_notifications">
118+
<x-slot:help>
119+
Receive an email when your application status changes.
120+
</x-slot:help>
121+
</x-forms::checkbox>
122+
```
123+
124+
Validation errors are displayed below the checkbox automatically, and the input receives the `is-invalid` class. Set `:show-errors="false"` to suppress both the messages and the invalid class.
125+
126+
```html
127+
<x-forms::checkbox name="accept_terms" required />
128+
129+
<x-forms::checkbox name="send_notifications" :show-errors="false" />
130+
```
131+
132+
The `required` option adds the HTML `required` attribute and the configured required indicator to the label. In an inline layout, the indicator appears on the separate field label. Add server-side validation rules in your application as well.
133+
134+
## Available Options
135+
136+
| Attribute | Type | Default | Description |
137+
| --- | --- | --- | --- |
138+
| `name` | `string` | **Required** | Input name, also used to generate the ID and look up bound values, old input, and validation errors. |
139+
| `label` | `string` | `''` | Label text. When empty, a translated, title-cased label is generated from `name`. |
140+
| `model` | `mixed` | `null` | Binding target. Uses the surrounding binding when omitted; `false` disables model binding for this checkbox. |
141+
| `default` | `bool` | `false` | Initial checked state when there is no old input and the bound value is `null`. |
142+
| `value` | `mixed` | `1` | Value submitted when checked, and the value matched against old input or a bound array. |
143+
| `show-errors` | `bool` | `true` | Displays validation errors and applies the invalid input class. |
144+
| `show-label` | `bool` | `true` | Controls the wrapping form group. The checkbox's own label remains visible. |
145+
| `required` | `bool` | `false` | Requires the checkbox to be checked and adds the configured required indicator. |
146+
| `inline` | `bool` | `false` | Places the field label and checkbox in separate columns. |
147+
| `floating` | `bool` | `false` | Applies the selected framework's floating form-group layout. |
148+
| `inline-label-class` | `string` | `''` | Overrides the inline label column classes; otherwise uses the framework configuration. |
149+
| `inline-input-class` | `string` | `''` | Overrides the inline input column classes; otherwise uses the framework configuration. |
150+
| `show-js-errors` | `bool` | `false` | Renders the `js-errors` component for client-side validation messages. |
151+
| `framework` | `string` | `''` | Uses `forms.framework` when omitted. Supports `bootstrap-5` and `material-admin-26`. |
152+
153+
The default slot supplies the checkbox label, and the named `help` slot supplies helper text. Additional HTML attributes, such as `id`, `class`, `disabled`, and `data-*`, are passed to the checkbox input.
154+
155+
```html
156+
<x-forms::checkbox name="send_notifications" id="notifications" disabled />
157+
```
158+
159+
To enable or disable other fields based on a checkbox's state, see [Conditional Wrapper](./conditional-wrapper.md).

0 commit comments

Comments
 (0)