1 1
# Toggle
2 2 3 3
> `v-b-toggle` is a light-weight directive for toggling the visibility of collapses and sidebars,
4 -
> and includes automated accessibility handling.
4 +
> and includes automated [WAI-ARIA accessibility](/docs/reference/accessibility) attribute handling.
5 5 6 6
## Overview
7 7
@@ -12,18 +12,27 @@ visibility state of the [`<b-collapse>`](/docs/components/collapse) and
12 12
Besides toggling the visibility of the target component, the directive automatically updates ARIA
13 13
accessibility attributes on the element it is applied to so that they reflect the visibility state
14 14
of the target component. Refer to the [Accessibility section](#accessibility) below for additional
15 -
details.
15 +
details and caveats.
16 16 17 17
## Directive syntax and usage
18 18 19 19
The directive is applied to the element or component that triggers the visibility of hte target. The
20 -
target component can be specified (via ID) as either a directive modifier(s) or as a string passed
21 -
to as the directive value:
22 - 23 -
- `v-b-toggle.my-collapse` - the directive modifier (multiple targets allowed)
24 -
- `v-b-toggle="'my-collapse'"` - the directive value (as a String, single target only)
25 - 26 -
Modifiers and the value can be used at the same time.
20 +
target component can be specified (via its ID) as either a directive modifier(s), the directive
21 +
argument, or as a string/array passed to as the directive value:
22 + 23 +
- `v-b-toggle.my-collapse` - the directive modifier (multiple targets allowed, each modifier is a
24 +
target ID)
25 +
- `v-b-toggle:my-collapse` - the directive argument
26 +
([Vue dynamic argument](https://vuejs.org/v2/guide/syntax.html#Dynamic-Arguments) is supported)
27 +
<span class="badge badge-info small" aria-label="Available in BootstrapVue v2.14.0+">v2.14.0+</span>
28 +
- `v-b-toggle="'my-collapse'"` - the directive value as a string ID
29 +
- `v-b-toggle="'my-collapse1 my-collapse2'"` - the directive value as a space separated string of
30 +
IDs
31 +
<span class="badge badge-info small" aria-label="Available in BootstrapVue v2.14.0+">v2.14.0+</span>
32 +
- `v-b-toggle="['my-collapse1', 'my-collapse2']"` - the directive value as an array of string IDs
33 +
<span class="badge badge-info small" aria-label="Available in BootstrapVue v2.14.0+">v2.14.0+</span>
34 + 35 +
Modifiers, argument, and the value can be used at the same time when targeting multiple components.
27 36 28 37
### Example usage
29 38
@@ -53,26 +62,59 @@ Modifiers and the value can be used at the same time.
53 62
<!-- v-b-toggle-directive.vue -->
54 63
```
55 64 65 +
## Hiding and showing content in the toggle trigger element
66 + 67 +
When using the `v-b-toggle` directive, the class `collapsed` will automatically be placed on the
68 +
trigger element when the target component is closed, and removed when open. As of BootstrapVue
69 +
`2.14.0`, the class `not-collapsed` will be applied when the target is _not_ closed.
70 + 71 +
**Example HTML markup:**
72 + 73 +
```html
74 +
<div>
75 +
<b-button v-b-toggle:my-collapse>
76 +
<span class="when-open">Close</span><span class="when-closed">Open</span> My Collapse
77 +
</b-button>
78 +
<b-collapse id="my-collapse">
79 +
<!-- Content here -->
80 +
</b-collapse>
81 +
</div>
82 +
```
83 + 84 +
**Example Custom CSS:**
85 + 86 +
```css
87 +
.collapsed > .when-open,
88 +
.not-collapsed > .when-closed {
89 +
display: none;
90 +
}
91 +
```
92 + 56 93
## Accessibility
57 94 58 95
The directive, for accessibility reasons, should be placed on an clickable interactive element such
59 96
as a `<button>` or `<b-button>`, which can easily be accessed by keyboard-only users and screen
60 -
reader users. Elements that do not natively have an accessibility role of `button` will have the
61 -
attributes `role="button"` and `tabindex="0"` applied, and will have the appropriate click and
62 -
keyboard handlers instantiated. Therefore it is _highly recommended_ to _not_ place the directive on
63 -
form controls other than buttons.
97 +
reader users. Elements that do not natively have an accessibility role of `button` (or `link`) will
98 +
have the attributes `role="button"` and `tabindex="0"` applied, and will have the appropriate click
99 +
handler instantiated. Therefore it is _highly recommended_ to _not_ place the directive on form
100 +
controls other than buttons.
64 101 65 102
The directive applies, and dynamically updates, the following ARIA attributes on the trigger
66 103
element:
67 104 68 -
- `aria-controls` - the ID of the collapse or sidebar component(s) being toggled
69 -
- `aria-expanded` - the visibility state of the collapse or sidebar
105 +
- `aria-controls` - the ID(s) of the collapse or sidebar component(s) being toggled
106 +
- `aria-expanded` - the visibility state of the collapse or sidebar (see the
107 +
[caveats section](#caveats-with-multiple-targets) below)
108 + 109 +
### Caveats with multiple targets
70 110 71 -
When the target component is _not_ expanded, the trigger element will have the class `collapsed`
72 -
applied. When the target component is expanded, the `collapsed` class will be removed from the
73 -
trigger element.
111 +
When multiple targets are specified, the value of the `aria-expanded` attribute may not be correct
112 +
if the individual target components can have their collapsed state controlled independently (either
113 +
via `v-model`, other controls with `v-b-toggle` directive, or CSS visibility).
74 114 75 115
## See also
76 116 77 117
- [`<b-collapse>`](/docs/components/collapse) Collapsible content with accordion support
78 118
- [`<b-sidebar>`](/docs/components/sidebar) Off-canvas sidebar
119 +
- [`<b-navbar-toggle>`](/docs/components/navbar#b-navbar-toggle-and-b-collapse-is-nav) Navbar
120 +
hamburger toggle button (based on `v-b-toggle` directive)
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4