From 061a6ad527b302d32bedc6c995f57624e908a403 Mon Sep 17 00:00:00 2001 From: "David W. Gray" Date: Fri, 1 Mar 2024 09:44:55 -0800 Subject: [PATCH] docs(BFormCheckbox): Cleanup (#1803) docs(BFormCheckbox): Add back in accessibility recommendation --- .../docs/src/docs/components/form-checkbox.md | 141 +++++++++--------- 1 file changed, 73 insertions(+), 68 deletions(-) diff --git a/apps/docs/src/docs/components/form-checkbox.md b/apps/docs/src/docs/components/form-checkbox.md index ce2d54bc5..ab55a00a9 100644 --- a/apps/docs/src/docs/components/form-checkbox.md +++ b/apps/docs/src/docs/components/form-checkbox.md @@ -146,7 +146,7 @@ const options = [ - `value` The selected value which will be set on `v-model` - `disabled` Disables item for selection -- `text` Display text, or html Display basic inline html +- `text` Display text, or `html` Display basic inline html `value` can be a string, number, or simple object. Avoid using complex types in values. @@ -271,66 +271,6 @@ const checkEx2Options = [ -## Checkbox values and `v-model` - -By default, `BFormCheckbox` value will be true when checked and false when unchecked. You can customize the checked and unchecked values by specifying the value and unchecked-value properties, respectively. - -When you have multiple checkboxes that bind to a single data state variable, you must provide an array reference (`[ ]`) to your v-model. - -Note that when v-model is bound to multiple checkboxes (i.e an array ref), the unchecked-value is **not used**. Only the value(s) of the checked checkboxes will be returned in the v-model bound array. You should provide a unique value for each checkbox's value prop (the default of true will not work when bound to an array). - -To pre-check any checkboxes, set the v-model to the value(s) of the checks that you would like pre-selected. - -When placing individual `BFormCheckbox` components within a `BFormCheckboxGroup`, most -props and the `v-model` are inherited from the `BFormCheckboxGroup`. - -Note: the unchecked-value prop does not affect the native ``'s `value` attribute, because browsers do not include unchecked boxes in form submissions. To guarantee that one of two values is submitted in a native `
` submit (e.g. 'yes' or 'no'), use radio inputs instead. This is the same limitation that Vue has with native checkbox inputs. - - - - {{ car }} - -
Selected: {{ concatSelectedCars}}
- - - -### Multiple checkboxes and accessibility - -When binding multiple checkboxes together, you must set the name prop to the same value for all `BFormCheckbox`s in the group individually. This will inform users of assistive technologies that the checkboxes are related and enables native browser keyboard navigation. - ## Inline and stacked checkboxes `BFormCheckboxGroup` components render inline checkboxes by default, while `BFormCheckbox` @@ -472,17 +412,80 @@ Use the `size` prop to control the size of the checkbox. The default size is med +## Checkbox values and `v-model` + +By default, `BFormCheckbox` value will be true when checked and false when unchecked. You can customize the checked and unchecked values by specifying the `value` and `unchecked-value` properties, respectively. + +When you have multiple checkboxes that bind to a single data state variable, you must provide an array reference (`[ ]`) to your v-model. + +Note that when `v-model` is bound to multiple checkboxes (i.e an array ref), the `unchecked-value` is **not used**. Only the value(s) of the checked checkboxes will be returned in the `v-model` bound array. You should provide a unique `value` for each checkbox's `value` prop (the default of `true` will not work when bound to an array). + +To pre-check any checkboxes, set the `v-model` to the value(s) of the checks that you would like pre-selected. + +When placing individual `BFormCheckbox` components within a `BFormCheckboxGroup`, most +props and the `v-model` are inherited from the `BFormCheckboxGroup`. + +**Note:** the `unchecked-value` prop does not affect the native ``'s `value` attribute, because browsers do not include unchecked boxes in form submissions. To guarantee that one of two values is submitted in a native `` submit (e.g. `'yes'` or `'no'`), use radio inputs instead. This is the same limitation that [Vue has with native checkbox inputs](https://vuejs.org/guide/essentials/forms.html#checkbox-1). + + + + {{ car }} + +
Selected: {{ concatSelectedCars}}
+ + + +### Multiple checkboxes and accessibility + +When binding multiple checkboxes together, you must set the `name` prop to the same value for all `BFormCheckbox`s in the group individually. This will inform users of assistive technologies that the checkboxes are related and enables native browser keyboard navigation. + +Whenever using multiple checkboxes, it is recommended that the checkboxes be placed in a [`BFormGroup`](/docs/components/form-group) component to associate a label with the entire group of checkboxes. See examples above. + ## Button style checkboxes You can optionally render checkboxes to appear as buttons, either individually, or in a group. -Button style checkboxes will have the class .active automatically applied to the label when they are in the checked state. +Button style checkboxes will have the class `.active` automatically applied to the label when they are in the checked state. ### Individual checkbox button style -A single checkbox can be rendered with a button appearance by setting the prop button to true. +A single checkbox can be rendered with a button appearance by setting the prop `button` to `true`. -Change the button variant by setting the button-variant prop to one of the standard Bootstrap button variants (see `BButton` for supported variants). The default variant is secondary. +Change the button variant by setting the `button-variant` prop to one of the standard Bootstrap button variants +(see [`BButton`](/docs/components/button) for supported variants). The default variant is `secondary`.
@@ -617,7 +620,7 @@ effect. ### Individual checkbox switch style -A single checkbox can be rendered with a switch appearance by setting the prop switch to true. +A single checkbox can be rendered with a switch appearance by setting the prop `switch` to `true`. Switch Checkbox (Checked: {{ switchChecked }}) @@ -784,6 +787,8 @@ const groupSwitchOptions = [ +**Note:** The `plain` prop has no effect when `button` or `buttons` is set. + ## Contextual states Bootstrap includes validation styles for valid and invalid states on most form controls. @@ -876,11 +881,11 @@ tell when the input becomes visible. Normally a checkbox input can only have two states: checked or unchecked. They can have any value, but they either submit that value (checked) or do not (unchecked) with a form submission (although BootstrapVueNext allows a value for the unchecked state on a single checkbox). -Visually, there are actually three states a checkbox can be in: checked, unchecked, or **indeterminate**. +Visually, there are actually three states a checkbox can be in: _checked_, _unchecked_, or **_indeterminate_**. -The indeterminate state is **visual only**. The checkbox is still either checked or unchecked as a value. That means the visual indeterminate state masks the real value of the checkbox, so that better make sense in your UI!. +The _indeterminate_ state is **visual only**. The checkbox is still either checked or unchecked as a value. That means the visual indeterminate state masks the real value of the checkbox, so that better make sense in your UI!. -`BFormCheckbox` supports setting this visual indeterminate state via a secondary named model called indeterminate (defaults to undefined). Clicking the checkbox will clear the indeterminate state and emit an `update:indeterminate=false` event. To reset the state set the indeterminate model value to true. +`BFormCheckbox` supports setting this visual indeterminate state via a secondary named model called `indeterminate` (defaults to `undefined`). Clicking the checkbox will clear the `indeterminate` state and emit an `update:indeterminate=false` event. To reset the state set `v-model:indeterminate` value to `true`. Click me to see what happens