Permalink
Browse files

feat(forms): New handling of form-select, form-radios and form-checkb…

…oxes (#994)

* Create loose-equal.js

* Update loose-equal.js

* Add looseEqual to utils

* Create form-option.vue

* Create form-optgroup.js

* Make b-form-optgroup and b-form-option available

alias b-form-optgroup as b-optgroup, and b-form-option as b-option

* Create form-radios.vue

* Update form-select.vue

* Update form-radios.vue

* Update index.js

* Create form-checkboxes.vue

* Update index.js

* Update form-options.js

* Update form-checkbox.vue

* Update form-radio.vue

* Update form-checkbox.vue

* Update form-radio.vue

* Update form-checkbox.vue

* Update form-radio.vue

* Update form-checkbox.vue

* Update form-checkbox.vue

* Update form-radio.vue

* Update form-radio.vue

* Update form-select.vue

* Update form-checkboxes.vue

* Update form-optgroup.js

* Update index.js

* Update meta.json

* Update index.js

* Rename docs/components/form-checkbox/meta.json to docs/components/form-checkboxes/meta.json

* Rename docs/components/form-checkbox/README.md to docs/components/form-checkboxes/README.md

* Rename docs/components/form-checkbox/index.js to docs/components/form-checkboxes/index.js

* Update and rename docs/components/form-radio/meta.json to docs/components/form-radios/meta.json

* Rename docs/components/form-radio/index.js to docs/components/form-radios/index.js

* Rename docs/components/form-radio/README.md to docs/components/form-radios/README.md

* Update meta.json

* Update meta.json

* Update index.js

* [form-select] Docs update

* Update form-checkboxes.vue

* [form-radios] Updated docs

* Update README.md

* Update README.md

* Update README.md

* Update index.js

* Rename form-checkboxes.vue to form-checkbox-group.vue

* Rename form-radios.vue to form-radio-group.vue

* Update meta.json

* Update meta.json

* Update index.js

* Update README.md

* Update README.md

* Update README.md

* Update demo.html

* [form-select] Docs: Switch to native <option> and <optgroup>

* Update meta.json

* [form-select] Switch to native browser <option>

* Update index.js

* Delete form-optgroup.js

* Delete form-option.vue

* resolve conflict

* Delete README.md

* Resolve conflict: This file should be deleted after merge

* Update README.md

* Update README.md

* Update form-options.js

* Update form-radio-group.vue

* Update form-checkbox-group.vue

* Update form-radio-group.vue

* Update form-radio.vue

* Create form-radio-check.js

* add new mixin

* [form-radio] Use form-radio-check mixin

* Update form-radio-check.js

* [form-checkbox] Use form-radio-check mixin

* Update form-checkbox.vue

* Update form-checkbox.vue

* Delete form-checkbox.js

* Update form-radio-group.vue

* Update form-checkbox-group.vue

* Update form-radio-group.vue

* [form-file] Add focus styling

* [form-file] Move focus styling to separate PR

* Update form-radio-check.js

* Update form-checkbox.vue

* Update form-options.js

* Update form-checkbox-group.vue

* Update form-checkbox.vue

* Update form-select.vue

* Update form-radio-check.js

* Update form-options.js

* Update form-radio-check.js

* Update form-radio.vue

* Update README.md

* Update README.md

* Update README.md

* Update README.md

* Update form-checkbox-group.vue

* Update form-radio-group.vue

* Update README.md

* Update form-radio.vue

* Update form-checkbox.vue

* Update form-checkbox.vue

* Update form-checkbox.vue

* Update README.md

* Mrged dev into forms/1x (#1038)

* chore(docs): Minor update to popover example

* fix(carousel): Prevent reflow trigger from being optimised out (#995)

* Update carousel.vue

* fix(popover+tooltip): Allow indiviual component imports (#999)

* [tooltip class] import BvEvent direct
* [popover class] Import ToolTip direct

* fix(form-group): Not applying label-for prop value (#1000)

* feat(modal): Add props to change the variant of the default modal buttons (#1004)

* Add props to set variant of modal footer buttons

* update docs

* feat(popover+tooltip): Add hide event listener on $root (#1003)

* feat(popover/tooltip): Add hide on $root events

Optimized adding/removing of events.

Only listen/watch to certain events while the tooltip/popover is open

Adds listener for `bv::hide::(popover|tooltip)` event on root to allow user to close all popovers or tooltips via emitting on $root.

* [popover component] Document bv:hide::popover event

* [tooltip component] Document bv:hide:tooltip event

* [popover directive] Document bv:hide:popover event

* [tooltip directive]: Document bv:hide::tooltip event

* feat(table): Refactor field formatter support + optimized sort-compare handling (#991)

* refactor(b-table): use original item object

* chore(table.spec): eslint format

* feat(b-table): Allow usr provided sortCopmpare to handle only specific fields

if user provided sortCompare returns `null` (or `undefined`), then we assume it doesn't handle sorting for the field specified by `sortBy`

* ESLint

* Always return formattedValue as `value` in scoped slot.

Unformatted value is available as property `unformatted` on scoped slot data.

* Update docs

* Update README.md

* Allow formattter to return html content

* Update README.md

* fix(table-docs): unexpected identifier error

* fix(table-docs): typo corrections ⌨💥

* Allow v-html without need for wrapper div via v-if/v-else

* fix(tooltip-popover): Click not triggered for elements with inner HTML elements in Chrome (#1006)

Issue #1005

* docs: Update getting started

* feat(dropdowns): Add hide() and show() methods (#1012)

Addresses issue #1011

* [form-group] Use dom utils

* [carousel] Use dom utils

* feat: dom utility methods (#1013)

* feat: dom utility methods

* Update index.js

* [tooltip.js] Use dom utils

* [dropdown.js] Use dom utils

* [scrollspy.js] Use dom utils

* feat: Use dom utils (#1017)

* feat: dom utility methods

* Update index.js

* [tooltip.js] Use dom utils

* [dropdown.js] Use dom utils

* [scrollspy.js] Use dom utils

* feat(array mixin): Add polyfill for Array.find for IE

* [modal] use dom utils

* [popover.vue] Use dom utils

* [tooltip.vue] Use dom utils

* feat(dom utils): Add getById method

* feat(tooltip+popover): Create mixin for common props and methods (#1021)

* feat(tooltip+popover): Create mixin for common props and methods

* make mixin available

* ESLint

* Update toolpop.js

* Update toolpop.js

* [tooltip.vue] use toolpop mixin

* [popover.vue] Use toolpop mixin

* chore: Update getting started

* fix type

* fix(lform-group): Missing return in target ID selection

* fix(link): clear router-link/href collision and remove old link mixin (#1016)

* fix(link): don't use href for router-links

* Merged dev into fix/link-router-to (#1018)

* [carousel] Use dom utils

* feat: dom utility methods (#1013)

* feat: dom utility methods

* Update index.js

* [tooltip.js] Use dom utils

* [dropdown.js] Use dom utils

* [scrollspy.js] Use dom utils

* feat: Use dom utils (#1017)

* feat: dom utility methods

* Update index.js

* [tooltip.js] Use dom utils

* [dropdown.js] Use dom utils

* [scrollspy.js] Use dom utils

* feat(array mixin): Add polyfill for Array.find for IE

* [modal] use dom utils

* [popover.vue] Use dom utils

* [tooltip.vue] Use dom utils

* fix: add fixes from PR #940

* fix: don't change href when disabled

Previously, we we're altering the href to a "#" when disabled. Since we already handle disabling the link via click handlers, there is no reason to alter the semantics of the link.

* Update toolpop.js

* Update popover.vue

* Update tooltip.vue

* fix: typos

* refactor: remove link mixin usage

* fix(docs): proper component reference

* fix: incorporate @pi0's typo fix

* fix(tooltip.js) Remove unneeded line of code

* fix(tabs): Remove aria-expanded in favor of aria-seleted

As per Bootstrap V4 PR twbs/bootstrap#23907

* fix: Add lodash.startcase to dependancies

`b-table` requires `lodash.startcase`

* feat(modal): Improve modal transitions, padding adjustments, and aditional features (#1024)

* [modal] Fix transitions

* Update modal.vue

* Update modal.vue

* [v-b-modal] Use new namespaced $root event

* [modal] Incorporate BvEvent

* Update modal.vue

* [modal] Scrolbar adjustments & observeDom

* Update modal.vue

* [modal] Add variants

* Update demo.html

* Update demo.js

* Update meta.json

* Update README.md

* [modal] Add modal-header-close slot

* Update meta.json

* [b-button-close] New functional component for close button

Used by b-modal and b-alert

* make b-button-close available

* Update button-close.js

* [button-close] Ensure click event propagation is stopped when disabled

* [modal] use b-btn-close functional component

* [alert] Use b-btn-close component

* Update modal.vue

* add b-button-close to b-button meta.json

* [tooltip.js] Update to use only new modal close namespaced event

* [tooltip+popover] Auto-append tooltip/popover to modal if in a modal

Save user from having to specify the modal as a container when tooltip/popover is inside a modal

* [popover.js] Use dom utils

* [dom utils] Add class and attribute methods

* Update dom.js

* [modal] Use new dom utils class/atttr methods

* Update dom.js

* Update dom.js

* Update dom.js

* [tooltip.js] Use new DOM utils methods

* [popover.js] Use new dom utils class/attribute methods

* [modal] Update docs

* fix: correct some typos

* fix: clear console errors

* fix: add const declarations

* [modal] Call onAfterEvent transition handler

* fix: evt names for modal triggering & is_visible typo

* fix: modal v-model typo

* fix(btn-close): allow for innerHTML override

* refactor(modal): use object for conditional props

* feat(docs): new modal examples

* Classes: Wrap in Boolean and remove dangling commas

* [modal] minor updates to docs

* feat(form-file): Add focus styling for custom-file input (#1033)

* feat(form-file): Add focus styling for custom-file input

* Update form-file.vue

* [form-file] Remove wrapper div when in plain mode

* add sizing to plain file input

Unfortunately there doesn't appear to be an option to size the custom-file input.

* Update form-file.vue

* fix(observedom): Callback not being called for changes other than childList changes (#1025)

* fix(observedom): Callback not being called for changes other than node inert/remove

Allow callback to be called based on passed options.

Previously it was only being called if nodes were added or inserted, regardless of which options were passed (i.e. attribute changes, childList, textnode changes, etc.)

This fix remove this restriction.

* Create loose-equal.js

* Update index.js

* Update observe-dom.js

* Update index.js

* Delete loose-equal.js

* Update observe-dom.js

* Update observe-dom.js

* Update observe-dom.js

* Update observe-dom.js

* [WIP] feat(collpase): Use new $root namespaced events (#1037)

feat(collpase): Use new $root namespaced events + dom utils

* Merge dev into forms/1x (#1040)

* chore(docs): Minor update to popover example

* fix(carousel): Prevent reflow trigger from being optimised out (#995)

* Update carousel.vue

* fix(popover+tooltip): Allow indiviual component imports (#999)

* [tooltip class] import BvEvent direct
* [popover class] Import ToolTip direct

* fix(form-group): Not applying label-for prop value (#1000)

* feat(modal): Add props to change the variant of the default modal buttons (#1004)

* Add props to set variant of modal footer buttons

* update docs

* feat(popover+tooltip): Add hide event listener on $root (#1003)

* feat(popover/tooltip): Add hide on $root events

Optimized adding/removing of events.

Only listen/watch to certain events while the tooltip/popover is open

Adds listener for `bv::hide::(popover|tooltip)` event on root to allow user to close all popovers or tooltips via emitting on $root.

* [popover component] Document bv:hide::popover event

* [tooltip component] Document bv:hide:tooltip event

* [popover directive] Document bv:hide:popover event

* [tooltip directive]: Document bv:hide::tooltip event

* feat(table): Refactor field formatter support + optimized sort-compare handling (#991)

* refactor(b-table): use original item object

* chore(table.spec): eslint format

* feat(b-table): Allow usr provided sortCopmpare to handle only specific fields

if user provided sortCompare returns `null` (or `undefined`), then we assume it doesn't handle sorting for the field specified by `sortBy`

* ESLint

* Always return formattedValue as `value` in scoped slot.

Unformatted value is available as property `unformatted` on scoped slot data.

* Update docs

* Update README.md

* Allow formattter to return html content

* Update README.md

* fix(table-docs): unexpected identifier error

* fix(table-docs): typo corrections ⌨💥

* Allow v-html without need for wrapper div via v-if/v-else

* fix(tooltip-popover): Click not triggered for elements with inner HTML elements in Chrome (#1006)

Issue #1005

* docs: Update getting started

* feat(dropdowns): Add hide() and show() methods (#1012)

Addresses issue #1011

* [form-group] Use dom utils

* [carousel] Use dom utils

* feat: dom utility methods (#1013)

* feat: dom utility methods

* Update index.js

* [tooltip.js] Use dom utils

* [dropdown.js] Use dom utils

* [scrollspy.js] Use dom utils

* feat: Use dom utils (#1017)

* feat: dom utility methods

* Update index.js

* [tooltip.js] Use dom utils

* [dropdown.js] Use dom utils

* [scrollspy.js] Use dom utils

* feat(array mixin): Add polyfill for Array.find for IE

* [modal] use dom utils

* [popover.vue] Use dom utils

* [tooltip.vue] Use dom utils

* feat(dom utils): Add getById method

* feat(tooltip+popover): Create mixin for common props and methods (#1021)

* feat(tooltip+popover): Create mixin for common props and methods

* make mixin available

* ESLint

* Update toolpop.js

* Update toolpop.js

* [tooltip.vue] use toolpop mixin

* [popover.vue] Use toolpop mixin

* chore: Update getting started

* fix type

* fix(lform-group): Missing return in target ID selection

* fix(link): clear router-link/href collision and remove old link mixin (#1016)

* fix(link): don't use href for router-links

* Merged dev into fix/link-router-to (#1018)

* [carousel] Use dom utils

* feat: dom utility methods (#1013)

* feat: dom utility methods

* Update index.js

* [tooltip.js] Use dom utils

* [dropdown.js] Use dom utils

* [scrollspy.js] Use dom utils

* feat: Use dom utils (#1017)

* feat: dom utility methods

* Update index.js

* [tooltip.js] Use dom utils

* [dropdown.js] Use dom utils

* [scrollspy.js] Use dom utils

* feat(array mixin): Add polyfill for Array.find for IE

* [modal] use dom utils

* [popover.vue] Use dom utils

* [tooltip.vue] Use dom utils

* fix: add fixes from PR #940

* fix: don't change href when disabled

Previously, we we're altering the href to a "#" when disabled. Since we already handle disabling the link via click handlers, there is no reason to alter the semantics of the link.

* Update toolpop.js

* Update popover.vue

* Update tooltip.vue

* fix: typos

* refactor: remove link mixin usage

* fix(docs): proper component reference

* fix: incorporate @pi0's typo fix

* fix(tooltip.js) Remove unneeded line of code

* fix(tabs): Remove aria-expanded in favor of aria-seleted

As per Bootstrap V4 PR twbs/bootstrap#23907

* fix: Add lodash.startcase to dependancies

`b-table` requires `lodash.startcase`

* feat(modal): Improve modal transitions, padding adjustments, and aditional features (#1024)

* [modal] Fix transitions

* Update modal.vue

* Update modal.vue

* [v-b-modal] Use new namespaced $root event

* [modal] Incorporate BvEvent

* Update modal.vue

* [modal] Scrolbar adjustments & observeDom

* Update modal.vue

* [modal] Add variants

* Update demo.html

* Update demo.js

* Update meta.json

* Update README.md

* [modal] Add modal-header-close slot

* Update meta.json

* [b-button-close] New functional component for close button

Used by b-modal and b-alert

* make b-button-close available

* Update button-close.js

* [button-close] Ensure click event propagation is stopped when disabled

* [modal] use b-btn-close functional component

* [alert] Use b-btn-close component

* Update modal.vue

* add b-button-close to b-button meta.json

* [tooltip.js] Update to use only new modal close namespaced event

* [tooltip+popover] Auto-append tooltip/popover to modal if in a modal

Save user from having to specify the modal as a container when tooltip/popover is inside a modal

* [popover.js] Use dom utils

* [dom utils] Add class and attribute methods

* Update dom.js

* [modal] Use new dom utils class/atttr methods

* Update dom.js

* Update dom.js

* Update dom.js

* [tooltip.js] Use new DOM utils methods

* [popover.js] Use new dom utils class/attribute methods

* [modal] Update docs

* fix: correct some typos

* fix: clear console errors

* fix: add const declarations

* [modal] Call onAfterEvent transition handler

* fix: evt names for modal triggering & is_visible typo

* fix: modal v-model typo

* fix(btn-close): allow for innerHTML override

* refactor(modal): use object for conditional props

* feat(docs): new modal examples

* Classes: Wrap in Boolean and remove dangling commas

* [modal] minor updates to docs

* feat(form-file): Add focus styling for custom-file input (#1033)

* feat(form-file): Add focus styling for custom-file input

* Update form-file.vue

* [form-file] Remove wrapper div when in plain mode

* add sizing to plain file input

Unfortunately there doesn't appear to be an option to size the custom-file input.

* Update form-file.vue

* fix(observedom): Callback not being called for changes other than childList changes (#1025)

* fix(observedom): Callback not being called for changes other than node inert/remove

Allow callback to be called based on passed options.

Previously it was only being called if nodes were added or inserted, regardless of which options were passed (i.e. attribute changes, childList, textnode changes, etc.)

This fix remove this restriction.

* Create loose-equal.js

* Update index.js

* Update observe-dom.js

* Update index.js

* Delete loose-equal.js

* Update observe-dom.js

* Update observe-dom.js

* Update observe-dom.js

* Update observe-dom.js

* [WIP] feat(collpase): Use new $root namespaced events (#1037)

feat(collpase): Use new $root namespaced events + dom utils

* Revert "fix(observedom): Callback not being called for changes other than childList changes" (#1039)

This reverts commit f44c5eb.

* Revert "fix(observedom): Callback not being called for changes other than childList changes (#1025)"

This reverts commit 88cfaef.

* revert observerdom changes

* Update form-checkbox.vue

* Update form-checkbox-group.vue

* Update form-checkbox.vue

* Update form-checkbox.vue

* Update form-checkbox.vue

* Update form-radio-check.js

* [form-group] include role=group in input-selector

* Update form-checkbox.vue

* Update README.md

* Update README.md

* Update README.md

* Update form-radio-check.js

* [form-checkbox-group]: Emit change event on user interaction

* [form-radio-group] Emit change event on user interaction

* Update meta.json

* Update meta.json

* Update sidebar.vue

* Update index.js

* [form-radios] Docs breaking change notice

* [form-select] Update docs with extra example
  • Loading branch information...
tmorehouse committed Sep 14, 2017
1 parent 93d702e commit 0a50398cd03e9b016ea1c87a82a79268f8e5945a
No changes.

This file was deleted.

Oops, something went wrong.
@@ -0,0 +1,368 @@
# Form Checkbox Inputs
> For cross browser consistency, `<b-form-checkbox-group>` and `<b-form-checkbox>` use
Bootstrap's custom checkbox input to replace the browser default checkbox input. It
is built on top of semantic and accessible markup, so it is a solid replacement for
the default checkbox input.
**Example 1:** Single checkbox
```html
<template>
<div>
<b-form-checkbox id="checkbox1"
v-model="status"
value="accepted"
unchecked-value="not_accepted">
I accept the terms and use
</b-form-checkbox>
<div>State: <strong>{{status}}</strong></div>
</div>
</template>
<script>
export default {
data: {
status: 'not_accepted'
}
}
</script>
<!-- form-checkbox-1.vue -->
```
**Example 2:** Multiple choice checkboxes
```html
<template>
<div>
<h5>Using options array:</h5>
<b-form-checkbox-group id="checkboxes1" name="flavour1" v-model="selected" :options="options">
</b-form-checkbox-group>
<h5 class="mt-3">Using sub-components:</h5>
<b-form-checkbox-group id="checkboxes2" name="flavour2" v-model="selected">
<b-form-checkbox value="orange">Orange</b-form-checkbox>
<b-form-checkbox value="apple">Apple</b-form-checkbox>
<b-form-checkbox value="pineapple">Pineapple</b-form-checkbox>
<b-form-checkbox value="grape">Grape</b-form-checkbox>
</b-form-checkbox-group>
<hr>
<div>Selected: <strong>{{ selected }}</strong></div>
</div>
</template>
<script>
export default {
data: {
selected: [], // Must be an array reference!
options: [
{text: 'Orange', value: 'orange'},
{text: 'Apple', value: 'apple'},
{text: 'Pineapple', value: 'pineapple'},
{text: 'Grape', value: 'grape'}
]
}
};
</script>
<!-- form-checkbox-2.vue -->
```
Feel free to mix and match `options` prop and `<b-form-checkbox>` in `<b-form-checkbox-group>`.
Manually placed `<b-form-checkbox>` inputs will appear _below_ any checkbox inputs generated by
the `options` prop. To have them apper _above_ the inputs generated by `options`, place them
in the named slot `first`.
## Options
Please see options in [`<b-form-select>`](/docs/components/form-select) docs for details on passing
options (value array) to `<b-form-checboxes>`.
## Inline and Stacked checkboxes
`<b-form-checbox>` components render as inline elements by default. Set the prop `stacked` on
`<b-form-checkbox-group>` to place each form control is on a separate line.
```html
<template>
<div>
<h5>Inline checkboxes (default)</h5>
<b-form-checkbox-group v-model="selected" name="flavour1" :options="options">
</b-form-checkbox-group>
<h5 class="mt-3">Stacked checkboxes</h5>
<b-form-checkbox-group stacked v-model="selected" name="flavour2" :options="options">
</b-form-checkbox-group>
</div>
</template>
<script>
export default {
data: {
selected: [], // Must be an array reference!
options: [
{text: 'Orange', value: 'orange'},
{text: 'Apple', value: 'apple'},
{text: 'Pineapple', value: 'pineapple'},
{text: 'Grape', value: 'grape'}
]
}
};
</script>
<!-- form-checkbox-stacked-1.vue -->
```
## Value(s)
By default, `<b-form-checkbox>` 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.
`v-model` binds to the `checked` property. 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 chcekboxes will
be returned in the `v-model` bound array. You should provide unique values for each
checkbox's `value` prop.
### Multiple checkboxes and accessibility
When binding multiple checkboxes together, you should set the `name` prop to the same
value for all `<b-formcheckbox>`s in the group individually or via the `name` prop
of `<b-form-checkbox-group>`. This will inform users of assitive technologies that the
checkboxes are related.
Whenever using multple checkboxes, it is recommended that the `<b-form-check-group>`
be placed in a [`<b-form-group>`](/docs/components/form-group) component to
associate a `<label>` with the entire group of checkboxes.
## Button style checkboxes
Render checkboxes with the look of a button by setting the prop `buttons` on `<b-form-checkbox-group>`.
Change the button variant by setting the `button-variant` prop to one of the standard Bootstrap
button variants (see [`<b-button>`](/docs/components/button) for supported variants). The
default `button-variant` is `secondary`.
Button style checkboxes will have the class `.active` automatically applied to the label
when they are in the _checked_ state.
```html
<template>
<div>
<h5>button style checkboxes</h5>
<b-form-checkbox-group buttons v-model="selected" name="butons1" :options="options">
</b-form-checkbox-group>
<h5 class="mt-3">
button style checkboxes with variant <code>primary</code> and large buttons
</h5>
<b-form-checkbox-group v-model="selected"
buttons
button-variant="primary"
size="lg"
name="buttons2"
:options="options">
</b-form-checkbox-group>
<h5 class="mt-3">Stacked (vertical) button style checkboxes</h5>
<b-form-checkbox-group buttons v-model="selected" stacked :options="options">
</b-form-checkbox-group>
</div>
</template>
<script>
export default {
data: {
selected: [], // Must be an array reference!
options: [
{text: 'Orange', value: 'orange'},
{text: 'Apple', value: 'apple'},
{text: 'Pineapple', value: 'pineapple'},
{text: 'Grape', value: 'grape'}
]
}
};
</script>
<!-- form-checkboxs-buttons.vue -->
```
## Contextual states
Bootstrap includes validation styles for `valid` and `invalid` states
on most form controls.
Generally speaking, you’ll want to use a particular state for specific types of feedback:
- `'invalid'` is great for when there’s a blocking or required field. A user must fill in
this field properly to submit the form.
- `'valid'` is ideal for situations when you have per-field validation throughout a form
and want to encourage a user through the rest of the fields.
- `null` Displays no validation state
To apply one of the contextual state icons on `<b-form-checkbox>`, set the `state` prop
to `'invalid'`, `'valid'`, or `null`.
**Note:** Contextual states are **not** supported when in button mode.
## Indeterminate (tri-state) support
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 don't (_unchecked_) with
a form submission (although Bootstrap-Vue allows a value for the _unchecked_ state)
_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!
`<b-form-checkbox>` supports setting this visual indeterminate state via the `indeterminate`
prop (defaults to `false`). Clicking the checkbox will clear its indeterminate state.
The `indeterminate` prop can be synced to the checkboxe's state by v-binding the
`indeterminate` prop with the `.sync` modifier.
**Note:** indeterminate is not supported in button mode, nor is it supported in
`<b-form-checkbox-group>` (multiple checkboxes).
**Single Indeterminate checkbox:**
```html
<template>
<div>
<b-form-checkbox v-model="checked" :indeterminate.sync="indeterminate">
Click me to see what happens
</b-form-checkbox>
<div class="mt-3">
Checked: <strong>{{ checked }}</strong><br>
Indeterminate: <strong>{{ indeterminate }}</strong>
</div>
<b-btn @click="toggleIndeterminate">Toggle Indeterminate State</b-btn>
</div>
</template>
<script>
export default {
data: {
checked: true,
indeterminate: true
},
methods: {
toggleIndeterminate() {
this.indeterminate = !this.indeterminate;
}
}
}
</script>
<!-- form-checkbox-indeterminate-1.vue -->
```
**Indeterminate checkbox use-case:**
```html
<template>
<b-card>
<b-form-checkbox v-model="allSelected"
:indeterminate="indeterminate"
aria-describedby="flavours"
aria-controls="flavours"
@change="toggleAll"
>
{{ allSelected ? 'Un-select' : 'Select' }}
All Flavors
</b-form-checkbox>
<b-form-checkbox-group id="flavors"
stacked
v-model="selected"
name="flavs"
:options="flavours"
class="ml-3"
aria-label="Individual flavours"
></b-form-checkbox-group>
<p aria-live="polite">
Selected: <strong>{{ selected }}</strong><br>
All Selected: <strong>{{ allSelected }}</strong><br>
Indeterminate: <strong>{{ indeterminate }}</strong><br>
</p>
</b-card>
</template>
<script>
export default {
data: {
flavours: ['Orange', 'Grape', 'Apple', 'Lime', 'Very Berry'],
selected: [],
allSelected: false,
indeterminate: false
},
methods: {
toggleAll() {
this.selected = this.allSelected ? this.flavours.slice() : [];
}
},
watch: {
selected(newVal, oldVal) {
// Handle changes in individual flavour checkboxes
if (newVal.length === 0) {
this.indeterminate = false;
this.allSelected = false;
} else if (newVal.length === this.flavours.length) {
this.indeterminate = false;
this.allSelected = true;
} else {
this.indeterminate = true;
this.allSelected = false;
}
}
}
}
</script>
<!-- form-checkbox-indeterminate-2.vue -->
```
**Note:** indeterminate is not supported in `button` mode, nor in multiple checkbox mode.
### Indeterminate state and accessibility
Not all screen readers will convey the indeterminate state to screen reader users.
So it is recommended to provide some form of textual feedback to the user (possibly
by via the `.sr-only` class) if the indeterminate state has special contextual
meaning in your application.
## Non custom check inputs (plain)
You can have `<b-form-checkbox-group>` or `<b-form-checkbox>` render a browser native
chechbox input by setting the `plain` prop.
```html
<template>
<div>
<h5>Plain inline checkboxes</h5>
<b-form-checkbox-group plain v-model="selected" :options="options" />
<h5 class="mt-3">Plain stacked checkboxes</h5>
<b-form-checkbox-group plain stacked v-model="selected" :options="options" />
</div>
</template>
<script>
export default {
data: {
selected: [], // Must be an array reference!
options: [
{text: 'Orange', value: 'orange'},
{text: 'Apple', value: 'apple'},
{text: 'Pineapple', value: 'pineapple'},
{text: 'Grape', value: 'grape'}
]
}
};
</script>
<!-- form-checkbox-plain-1.vue -->
```
**Note:** The `plain` prop has no effect when `button` is set.
## Aliases
- `<b-form-checbox-group>` can be used by the shorter aliases `<b-checkbox-group>` and `<b-check-group>`.
- `<b-form-checkbox>` can be used by thes shorter aliases `<b-checkbox>` and `<b-check>`.
Oops, something went wrong.

0 comments on commit 0a50398

Please sign in to comment.