@gitlab/ui 84.2.0 → 85.0.0

package/src/vendor/bootstrap-vue/src/components/form-checkbox/README.md

@@ -0,0 +1,862 @@
+# Form Checkbox
+
+> 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="checkbox-1"
+      v-model="status"
+      name="checkbox-1"
+      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() {
+      return {
+        status: 'not_accepted'
+      }
+    }
+  }
+</script>
+
+<!-- b-form-checkbox.vue -->
+```
+
+**Example 2:** Multiple choice checkboxes
+
+```html
+<template>
+  <div>
+    <b-form-group label="Using options array:" v-slot="{ ariaDescribedby }">
+      <b-form-checkbox-group
+        id="checkbox-group-1"
+        v-model="selected"
+        :options="options"
+        :aria-describedby="ariaDescribedby"
+        name="flavour-1"
+      ></b-form-checkbox-group>
+    </b-form-group>
+
+    <b-form-group label="Using sub-components:" v-slot="{ ariaDescribedby }">
+      <b-form-checkbox-group
+        id="checkbox-group-2"
+        v-model="selected"
+        :aria-describedby="ariaDescribedby"
+        name="flavour-2"
+      >
+        <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>
+    </b-form-group>
+
+    <div>Selected: <strong>{{ selected }}</strong></div>
+  </div>
+</template>
+
+<script>
+  export default {
+    data() {
+      return {
+        selected: [], // Must be an array reference!
+        options: [
+          { text: 'Orange', value: 'orange' },
+          { text: 'Apple', value: 'apple' },
+          { text: 'Pineapple', value: 'pineapple' },
+          { text: 'Grape', value: 'grape' }
+        ]
+      }
+    }
+  }
+</script>
+
+<!-- b-form-checkbox-multiple.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 appear _above_ the inputs generated by `options`, place them in the
+named slot `first`.
+
+## Checkbox group options array
+
+`options` can be an array of strings or objects. Available fields:
+
+- **`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
+
+`value` can be a string, number, or simple object. Avoid using complex types in values.
+
+If both `html` and `text` are provided, `html` will take precedence. Only basic/native HTML is
+supported in the `html` field (components will not work). Note that not all browsers will render
+inline html (i.e. `<i>`, `<strong>`, etc.) inside `<option>` elements of a `<select>`.
+
+<p class="alert alert-danger">
+  <strong>Be cautious</strong> of placing user supplied content in the <code>html</code> field,
+  as it may make you vulnerable to
+  <a class="alert-link" href="https://en.wikipedia.org/wiki/Cross-site_scripting">
+  <abbr title="Cross Site Scripting Attacks">XSS attacks</abbr></a>, if you do not first
+  <a class="alert-link" href="https://en.wikipedia.org/wiki/HTML_sanitization">sanitize</a> the
+  user supplied string.
+</p>
+
+<!-- eslint-disable no-unused-vars -->
+
+```js
+const options = ['A', 'B', 'C', { text: 'D', value: { d: 1 }, disabled: true }, 'E', 'F']
+```
+
+If an array entry is a string, it will be used for both the generated `value` and `text` fields.
+
+You can mix using strings and [objects](#options-as-an-array-of-objects) in the array.
+
+Internally, BootstrapVue will convert the above array to the following array (the
+[array of objects](#options-as-an-array-of-objects)) format:
+
+<!-- eslint-disable no-unused-vars -->
+
+```js
+const options = [
+  { text: 'A', value: 'A', disabled: false },
+  { text: 'B', value: 'B', disabled: false },
+  { text: 'C', value: 'C', disabled: false },
+  { text: 'D', value: { d: 1 }, disabled: true },
+  { text: 'E', value: 'E', disabled: false },
+  { text: 'F', value: 'F', disabled: false }
+]
+```
+
+### Options as an array of objects
+
+<!-- eslint-disable no-unused-vars -->
+
+```js
+const options = [
+  { text: 'Item 1', value: 'first' },
+  { text: 'Item 2', value: 'second' },
+  { html: '<b>Item</b> 3', value: 'third', disabled: true },
+  { text: 'Item 4' },
+  { text: 'Item 5', value: { foo: 'bar', baz: true } }
+]
+```
+
+If `value` is missing, then `text` will be used as both the `value` and `text` fields. If you use
+the `html` property, you **must** supply a `value` property.
+
+Internally, BootstrapVue will convert the above array to the following array (the
+[array of objects](#options-as-an-array-of-objects)) format:
+
+<!-- eslint-disable no-unused-vars -->
+
+```js
+const options = [
+  { text: 'Item 1', value: 'first', disabled: false },
+  { text: 'Item 2', value: 'second', disabled: false },
+  { html: '<b>Item</b> 3', value: 'third', disabled: true },
+  { text: 'Item 4', value: 'Item 4', disabled: false },
+  { text: 'Item 5', value: 'E', disabled: false }
+]
+```
+
+### Changing the option field names
+
+If you want to customize the field property names (for example using `name` field for display
+`text`) you can easily change them by setting the `text-field`, `html-field`, `value-field`, and
+`disabled-field` props to a string that contains the property name you would like to use:
+
+```html
+<template>
+  <div>
+    <b-form-checkbox-group
+      v-model="selected"
+      :options="options"
+      class="mb-3"
+      value-field="item"
+      text-field="name"
+      disabled-field="notEnabled"
+    ></b-form-checkbox-group>
+    <div class="mt-3">Selected: <strong>{{ selected }}</strong></div>
+  </div>
+</template>
+
+<script>
+  export default {
+    data() {
+      return {
+        selected: [],
+        options: [
+          { item: 'A', name: 'Option A' },
+          { item: 'B', name: 'Option B' },
+          { item: 'D', name: 'Option C', notEnabled: true },
+          { item: { d: 1 }, name: 'Option D' }
+        ]
+      }
+    }
+  }
+</script>
+
+<!-- b-form-checkbox-group-options-fields.vue -->
+```
+
+## Inline and stacked checkboxes
+
+`<b-form-checkbox-group>` components render inline checkboxes by default, while `<b-form-checkbox>`
+renders block-level (stacked) checkboxes.
+
+Set the prop `stacked` on `<b-form-checkbox-group>` to place each form control one over the other,
+or if using individual checkboxes not inside a `<b-form-checkbox-group>`, set the `inline` prop on
+`<b-form-checkbox>`.
+
+```html
+<template>
+  <div>
+    <b-form-group
+      label="Form-checkbox-group inline checkboxes (default)"
+      v-slot="{ ariaDescribedby }"
+    >
+      <b-form-checkbox-group
+        v-model="selected"
+        :options="options"
+        :aria-describedby="ariaDescribedby"
+        name="flavour-1a"
+      ></b-form-checkbox-group>
+    </b-form-group>
+
+    <b-form-group
+      label="Form-checkbox-group stacked checkboxes"
+      v-slot="{ ariaDescribedby }"
+    >
+      <b-form-checkbox-group
+        v-model="selected"
+        :options="options"
+        :aria-describedby="ariaDescribedby"
+        name="flavour-2a"
+        stacked
+      ></b-form-checkbox-group>
+    </b-form-group>
+
+    <b-form-group
+      label="Individual stacked checkboxes (default)"
+      v-slot="{ ariaDescribedby }"
+    >
+      <b-form-checkbox
+        v-for="option in options"
+        v-model="selected"
+        :key="option.value"
+        :value="option.value"
+        :aria-describedby="ariaDescribedby"
+        name="flavour-3a"
+      >
+        {{ option.text }}
+      </b-form-checkbox>
+    </b-form-group>
+
+    <b-form-group
+      label="Individual inline checkboxes"
+      v-slot="{ ariaDescribedby }"
+    >
+      <b-form-checkbox
+        v-for="option in options"
+        v-model="selected"
+        :key="option.value"
+        :value="option.value"
+        :aria-describedby="ariaDescribedby"
+        name="flavour-4a"
+        inline
+      >
+        {{ option.text }}
+      </b-form-checkbox>
+    </b-form-group>
+  </div>
+</template>
+
+<script>
+  export default {
+    data() {
+      return {
+        selected: [], // Must be an array reference!
+        options: [
+          { text: 'Orange', value: 'orange' },
+          { text: 'Apple', value: 'apple' },
+          { text: 'Pineapple', value: 'pineapple' },
+          { text: 'Grape', value: 'grape' }
+        ]
+      }
+    }
+  }
+</script>
+
+<!-- b-form-checkbox-stacked.vue -->
+```
+
+## Control sizing
+
+Use the `size` prop to control the size of the checkbox. The default size is medium. Supported size
+values are `sm` (small) and `lg` (large).
+
+```html
+<div>
+  <b-form-checkbox size="sm">Small</b-form-checkbox>
+  <b-form-checkbox>Default</b-form-checkbox>
+  <b-form-checkbox size="lg">Large</b-form-checkbox>
+</div>
+
+<!-- form-checkbox-sizes.vue -->
+```
+
+Sizes can be set on individual `<b-form-checkbox>` components, or inherited from the size setting of
+`<b-form-checkbox-group>`.
+
+**Note:** Bootstrap v4.x does not natively support sizes for the custom checkbox control. However,
+BootstrapVue includes custom SCSS/CSS that adds support for sizing the custom checkboxes.
+
+## Checkbox values and `v-model`
+
+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, respectively.
+
+The `v-model` binds to the `checked` prop. When you have multiple checkboxes that bind to a single
+data state variable, you **must** provide an array reference (`[]`) to your `v-model`. Do not use
+the `checked` prop directly.
+
+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 radios, set the `v-model` to the value(s) of the checks that you would like
+pre-selected.
+
+When placing individual `<b-form-checkbox>` components within a `<b-form-checkbox-group>`, most
+props and the `v-model` are inherited from the `<b-form-checkbox-group>`.
+
+**Note:** the `unchecked-value` prop _does not_ affect the native `<input>`'s `value` attribute,
+because browsers don't include unchecked boxes in form submissions. To guarantee that one of two
+values is submitted in a native `<form>` 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/v2/guide/forms.html#Checkbox-1).
+
+### Multiple checkboxes and accessibility
+
+When binding multiple checkboxes together, you must set the `name` prop to the same value for all
+`<b-form-checkbox>`s in the group individually or via the `name` prop of `<b-form-checkbox-group>`.
+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
+[`<b-form-group>`](/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.
+
+### Individual checkbox button style
+
+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 [`<b-button>`](/docs/components/button) for supported variants). The default
+variant is `secondary`.
+
+```html
+<template>
+  <div>
+    <b-form-checkbox v-model="checked1" name="check-button" button>
+      Button Checkbox <b>(Checked: {{ checked1 }})</b>
+    </b-form-checkbox>
+    <b-form-checkbox v-model="checked2" name="check-button" button button-variant="info">
+      Button Checkbox <b>(Checked: {{ checked2 }})</b>
+    </b-form-checkbox>
+  </div>
+</template>
+
+<script>
+  export default {
+    data() {
+      return {
+        checked1: false,
+        checked2: false
+      }
+    }
+  }
+</script>
+
+<!-- b-form-checkbox-button.vue -->
+```
+
+The `inline` prop has no effect on individual button-style checkboxes.
+
+### Grouped button style checkboxes
+
+Render groups of checkboxes with the look of a button-group 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`.
+
+```html
+<template>
+  <div>
+    <b-form-group
+      label="Button-group style checkboxes"
+      v-slot="{ ariaDescribedby }"
+    >
+      <b-form-checkbox-group
+        v-model="selected"
+        :options="options"
+        :aria-describedby="ariaDescribedby"
+        name="buttons-1"
+        buttons
+      ></b-form-checkbox-group>
+    </b-form-group>
+
+    <b-form-group
+      label="Button-group style checkboxes with variant primary and large buttons"
+      v-slot="{ ariaDescribedby }"
+    >
+      <b-form-checkbox-group
+        v-model="selected"
+        :options="options"
+        :aria-describedby="ariaDescribedby"
+        buttons
+        button-variant="primary"
+        size="lg"
+        name="buttons-2"
+      ></b-form-checkbox-group>
+    </b-form-group>
+
+    <b-form-group
+      label="Stacked (vertical) button-group style checkboxes"
+      v-slot="{ ariaDescribedby }"
+    >
+      <b-form-checkbox-group
+        v-model="selected"
+        :options="options"
+        :aria-describedby="ariaDescribedby"
+        stacked
+        buttons
+      ></b-form-checkbox-group>
+    </b-form-group>
+  </div>
+</template>
+
+<script>
+  export default {
+    data() {
+      return {
+        selected: [], // Must be an array reference!
+        options: [
+          { text: 'Orange', value: 'orange' },
+          { text: 'Apple', value: 'apple' },
+          { text: 'Pineapple', value: 'pineapple' },
+          { text: 'Grape', value: 'grape' }
+        ]
+      }
+    }
+  }
+</script>
+
+<!-- b-form-checkbox-button-group.vue -->
+```
+
+## Switch style checkboxes
+
+Switch styling is supported on `<b-form-checkbox>` and `<b-form-checkbox-group>` components.
+
+**Note:** If the checkbox is in [button mode](#button-style-checkboxes), switch mode will have no
+effect.
+
+### Individual checkbox switch style
+
+A single checkbox can be rendered with a switch appearance by setting the prop `switch` to `true`
+
+```html
+<template>
+  <div>
+    <b-form-checkbox v-model="checked" name="check-button" switch>
+      Switch Checkbox <b>(Checked: {{ checked }})</b>
+    </b-form-checkbox>
+  </div>
+</template>
+
+<script>
+  export default {
+    data() {
+      return {
+        checked: false
+      }
+    }
+  }
+</script>
+
+<!-- b-form-checkbox-switch.vue -->
+```
+
+### Grouped switch style checkboxes
+
+Render groups of checkboxes with the look of a switches by setting the prop `switches` on
+`<b-form-checkbox-group>`.
+
+```html
+<template>
+  <div>
+    <b-form-group
+      label="Inline switch style checkboxes"
+      v-slot="{ ariaDescribedby }"
+    >
+      <b-form-checkbox-group
+        v-model="selected"
+        :options="options"
+        :aria-describedby="ariaDescribedby"
+        switches
+      ></b-form-checkbox-group>
+    </b-form-group>
+
+    <b-form-group
+      label="Stacked (vertical) switch style checkboxes"
+      v-slot="{ ariaDescribedby }"
+    >
+      <b-form-checkbox-group
+        v-model="selected"
+        :options="options"
+        :aria-describedby="ariaDescribedby"
+        switches
+        stacked
+      ></b-form-checkbox-group>
+    </b-form-group>
+  </div>
+</template>
+
+<script>
+  export default {
+    data() {
+      return {
+        selected: [], // Must be an array reference!
+        options: [
+          { text: 'Red', value: 'red' },
+          { text: 'Green', value: 'green' },
+          { text: 'Yellow (disabled)', value: 'yellow', disabled: true },
+          { text: 'Blue', value: 'blue' }
+        ]
+      }
+    }
+  }
+</script>
+
+<!-- b-form-checkboxes-switch-group.vue -->
+```
+
+### Switch sizing
+
+Use the `size` prop to control the size of the switch. The default size is medium. Supported size
+values are `sm` (small) and `lg` (large).
+
+```html
+<div>
+  <b-form-checkbox switch size="sm">Small</b-form-checkbox>
+  <b-form-checkbox switch>Default</b-form-checkbox>
+  <b-form-checkbox switch size="lg">Large</b-form-checkbox>
+</div>
+
+<!-- form-checkbox-switch-sizes.vue -->
+```
+
+Sizes can be set on individual `<b-form-checkbox>` components, or inherited from the size setting of
+`<b-form-checkbox-group>`.
+
+**Note:** Bootstrap v4.x does not natively support sizes for the custom switch control. However,
+BootstrapVue includes custom SCSS/CSS that adds support for sizing the custom switches.
+
+## Non custom check inputs (plain)
+
+You can have `<b-form-checkbox-group>` or `<b-form-checkbox>` render a browser native checkbox input
+by setting the `plain` prop.
+
+```html
+<template>
+  <div>
+    <b-form-group label="Plain inline checkboxes" v-slot="{ ariaDescribedby }">
+      <b-form-checkbox-group
+        v-model="selected"
+        :options="options"
+        :aria-describedby="ariaDescribedby"
+        plain
+      ></b-form-checkbox-group>
+    </b-form-group>
+
+    <b-form-group label="Plain stacked checkboxes" v-slot="{ ariaDescribedby }">
+      <b-form-checkbox-group
+        v-model="selected"
+        :options="options"
+        :aria-describedby="ariaDescribedby"
+        plain
+        stacked
+      ></b-form-checkbox-group>
+    </b-form-group>
+  </div>
+</template>
+
+<script>
+  export default {
+    data() {
+      return {
+        selected: [], // Must be an array reference!
+        options: [
+          { text: 'Orange', value: 'orange' },
+          { text: 'Apple', value: 'apple' },
+          { text: 'Pineapple', value: 'pineapple' },
+          { text: 'Grape', value: 'grape' }
+        ]
+      }
+    }
+  }
+</script>
+
+<!-- b-form-checkbox-plain.vue -->
+```
+
+**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.
+
+Generally speaking, you'll want to use a particular state for specific types of feedback:
+
+- `false` (denotes invalid state) is great for when there's a blocking or required field. A user
+  must fill in this field properly to submit the form.
+- `true` (denotes valid state) 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 (neither valid nor invalid)
+
+To apply one of the contextual state icons on `<b-form-checkbox>`, set the `state` prop to `false`
+(for invalid), `true` (for valid), or `null` (no validation state).
+
+**Note:** Contextual states are **not** supported when in button mode.
+
+### Contextual state and validation example
+
+```html
+<template>
+  <div>
+    <b-form-checkbox-group
+      v-model="value"
+      :options="options"
+      :state="state"
+      name="checkbox-validation"
+    >
+      <b-form-invalid-feedback :state="state">Please select two</b-form-invalid-feedback>
+      <b-form-valid-feedback :state="state">Thank you</b-form-valid-feedback>
+    </b-form-checkbox-group>
+  </div>
+</template>
+
+<script>
+  export default {
+    data() {
+      return {
+        value: [],
+        options: [
+          { text: 'First Check', value: 'first' },
+          { text: 'Second Check', value: 'second' },
+          { text: 'Third Check', value: 'third' }
+        ]
+      }
+    },
+    computed: {
+      state() {
+        return this.value.length === 2
+      }
+    }
+  }
+</script>
+
+<!-- form-checkbox-validation.vue -->
+```
+
+### Required constraint
+
+When using individual `<b-form-checkbox>` components (not in a `<b-form-checkbox-group>`), and you
+want the checkbox(es) to be `required` in your form, you **must** provide a `name` on each
+`<b-form-checkbox>` in order for the required constraint to work. All `<b-form-checkbox>` components
+tied to the same `v-model` **must** have the same `name`.
+
+The `name` is required in order for Assistive Technologies (such as screen readers, and keyboard
+only users) to know which checkboxes belong to the same form variable (the name also automatically
+enables native browser keyboard navigation), hence `required` will only work if `name` is set.
+`<b-form-checkbox-group>` will automatically generate a unique input name if one is not provided on
+the group.
+
+## Autofocus
+
+When the `autofocus` prop is set on `<b-form-checkbox>`, the input will be auto-focused when it is
+inserted (i.e. **mounted**) into the document, or re-activated when inside a Vue `<keep-alive>`
+component. Note that this prop **does not** set the `autofocus` attribute on the input, nor can it
+tell when the input becomes visible.
+
+## 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 BootstrapVue 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_**.
+
+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 checkbox's state by v-binding the `indeterminate` prop with the `.sync`
+modifier.
+
+**Note:** indeterminate styling is not supported in button or switch 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-button @click="toggleIndeterminate">Toggle Indeterminate State</b-button>
+  </div>
+</template>
+
+<script>
+  export default {
+    data() {
+      return {
+        checked: true,
+        indeterminate: true
+      }
+    },
+    methods: {
+      toggleIndeterminate() {
+        this.indeterminate = !this.indeterminate
+      }
+    }
+  }
+</script>
+
+<!-- b-form-checkbox-indeterminate.vue -->
+```
+
+**Indeterminate checkbox use-case example:**
+
+```html
+<template>
+  <div>
+    <b-form-group>
+      <template #label>
+        <b>Choose your flavours:</b><br>
+        <b-form-checkbox
+          v-model="allSelected"
+          :indeterminate="indeterminate"
+          aria-describedby="flavours"
+          aria-controls="flavours"
+          @change="toggleAll"
+        >
+          {{ allSelected ? 'Un-select All' : 'Select All' }}
+        </b-form-checkbox>
+      </template>
+
+      <template v-slot="{ ariaDescribedby }">
+        <b-form-checkbox-group
+          id="flavors"
+          v-model="selected"
+          :options="flavours"
+          :aria-describedby="ariaDescribedby"
+          name="flavors"
+          class="ml-4"
+          aria-label="Individual flavours"
+          stacked
+        ></b-form-checkbox-group>
+      </template>
+    </b-form-group>
+
+    <div>
+      Selected: <strong>{{ selected }}</strong><br>
+      All Selected: <strong>{{ allSelected }}</strong><br>
+      Indeterminate: <strong>{{ indeterminate }}</strong>
+    </div>
+  </div>
+</template>
+
+<script>
+  export default {
+    data() {
+      return {
+        flavours: ['Orange', 'Grape', 'Apple', 'Lime', 'Very Berry'],
+        selected: [],
+        allSelected: false,
+        indeterminate: false
+      }
+    },
+    methods: {
+      toggleAll(checked) {
+        this.selected = checked ? this.flavours.slice() : []
+      }
+    },
+    watch: {
+      selected(newValue, oldValue) {
+        // Handle changes in individual flavour checkboxes
+        if (newValue.length === 0) {
+          this.indeterminate = false
+          this.allSelected = false
+        } else if (newValue.length === this.flavours.length) {
+          this.indeterminate = false
+          this.allSelected = true
+        } else {
+          this.indeterminate = true
+          this.allSelected = false
+        }
+      }
+    }
+  }
+</script>
+
+<!-- b-form-checkbox-indeterminate-multiple.vue -->
+```
+
+**Note:** indeterminate is not supported in `button` mode, nor in multiple checkbox mode. Also pay
+attention that plain checkbox (i.e. with prop `plain`) also supports indeterminate state on
+Windows/Linux/Mac/Android, but not on iOS.
+
+### 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.
+
+<!-- Component reference added automatically from component package.json -->