Skip to content

Commit 541fada

Browse files
tmorehousetmorehouse
authored
feat(docs): Improved collapse examples and documentation
1 parent d95321b commit 541fada

File tree

1 file changed

+177
-101
lines changed

1 file changed

+177
-101
lines changed

‎docs/components/collapse/README.md

+177-101
Original file line numberDiff line numberDiff line change
@@ -1,163 +1,239 @@
11
# Collapse
22

3-
> The Bootstrap `<b-collapse>` component and `v-b-toggle` directive allows you to
4-
toggle content visibility on your pages.
3+
> The Bootstrap-Vue `<b-collapse>` component and `v-b-toggle` directive allows you to
4+
toggle content visibility on your pages. Includes support for making accordions.
55

6-
**Example 1:** Basic collapse
76
```html
87
<div>
9-
<p>
108
<b-btn v-b-toggle.collapse1 variant="primary">Toggle Collapse</b-btn>
11-
</p>
12-
13-
<b-collapse id="collapse1">
14-
<b-card>
15-
Collapse contents Here
16-
<b-btn v-b-toggle.collapse2 size="sm">Toggle Inner Collapse</b-btn>
17-
<b-collapse id=collapse2 class="mt-2">
18-
<b-card>Hello!</b-card>
9+
<b-collapse id="collapse1" class="mt-2">
10+
<b-card>
11+
<p class="card-text">Collapse contents Here</p>
12+
<b-btn v-b-toggle.collapse1_inner size="sm">Toggle Inner Collapse</b-btn>
13+
<b-collapse id=collapse1_inner class="mt-2">
14+
<b-card>Hello!</b-card>
1915
</b-collapse>
20-
</b-card>
16+
</b-card>
2117
</b-collapse>
2218
</div>
2319

2420
<!-- collapse-1.vue -->
2521
```
2622

27-
**Example 2:** Accordion
28-
```html
29-
<div>
30-
<b-btn block v-b-toggle.accordion1 variant="primary">Accordion 1</b-btn>
31-
<b-collapse id="accordion1" visible accordion="my-accordion">
32-
<b-card>
33-
Accordion 1 contents Here
34-
</b-card>
35-
</b-collapse>
36-
<b-btn block class="mt-1" v-b-toggle.accordion2 variant="primary">Accordion 2</b-btn>
37-
<b-collapse id="accordion2" accordion="my-accordion">
38-
<b-card>
39-
Accordion 2 contents Here
40-
</b-card>
41-
</b-collapse>
42-
<b-btn block class="mt-1" v-b-toggle.accordion3 variant="primary">Accordion 3</b-btn>
43-
<b-collapse id="accordion3" accordion="my-accordion">
44-
<b-card>
45-
Accordion 3 contents Here
46-
</b-card>
47-
</b-collapse>
48-
</div>
49-
50-
<!-- collapse-2.vue -->
51-
```
23+
## Usage
5224

5325
Other elements can easily toggle `<b-collapse>` components using the `v-b-toggle` directive.
5426

5527
```html
56-
<!-- Using modifiers -->
57-
<b-btn v-b-toggle.collapse1>Toggle Collapse</b-btn>
28+
<div>
29+
<!-- Using modifiers -->
30+
<b-btn v-b-toggle.collapse2 class="m-1">Toggle Collapse</b-btn>
5831

59-
<!-- Using value -->
60-
<b-btn v-b-toggle="'collapse1'">Toggle Collapse</b-btn>
32+
<!-- Using value -->
33+
<b-btn v-b-toggle="'collapse2'" class="m-1">Toggle Collapse</b-btn>
6134

62-
<!-- element to collapse -->
63-
<b-collapse id="collapse1">
35+
<!-- element to collapse -->
36+
<b-collapse id="collapse2">
6437
<b-card>
6538
I am collapsable content!
6639
</b-card>
67-
</b-collapse>
40+
</b-collapse>
41+
</div>
42+
43+
<!-- collapse-2.vue -->
6844
```
6945

46+
### Initial visibility (start expanded)
7047
To make the `<b-collapse>` show initially, set the `visible` prop:
7148

7249
```html
73-
<b-btn v-b-toggle.collapse1>Toggle Collapse</b-btn>
74-
75-
<b-collapse visible id="collapse1">
50+
<div>
51+
<b-btn v-b-toggle.collapse3 class="m-1">Toggle Collapse</b-btn>
52+
<b-collapse visible id="collapse3">
7653
<b-card>
7754
I should start open!
7855
</b-card>
79-
</b-collapse>
56+
</b-collapse>
57+
</div>
58+
59+
<!-- collapse-3.vue -->
8060
```
8161

82-
The component's collapsed (visible) state can also be set with `v-model` which binds to the visible prop:
62+
### `v-model` support
63+
The component's collapsed (visible) state can also be set with `v-model` which
64+
binds internally to the `visible` prop.
8365

84-
```html
85-
<b-btn @click="showCollapse = !showCollapse">Toggle Collapse</b-btn>
66+
Note, when using v-model to control `<b-collapse>`, the `aria-*` attributes and
67+
class `collapsed` are not automaticaly placed on the trigger button (as is the case
68+
when using the `v-b-toggle` directive). In this example we must control them ourselves.
8669

87-
<b-collapse v-model="showCollapse" id="collapse1">
88-
<b-card>
89-
I should start open!
90-
</b-card>
91-
</b-collapse>
70+
```html
71+
<template>
72+
<div>
73+
<b-btn @click="showCollapse = !showCollapse"
74+
:class="showCollapse ? 'collapsed' : null"
75+
aria-controls="collapse4"
76+
:aria-expanded="showCollapse ? 'true' : 'false'">
77+
Toggle Collapse
78+
</b-btn>
79+
<b-collapse class="mt-2" v-model="showCollapse" id="collapse4">
80+
<b-card>
81+
I should start open!
82+
</b-card>
83+
</b-collapse>
84+
</div>
85+
</template>
9286

9387
<script>
94-
{
95-
// inside the vue
96-
data() {
97-
return {
98-
showCollapse: true
99-
}
100-
}
101-
}
88+
export default {
89+
data: {
90+
showCollapse: true
91+
}
92+
};
10293
</script>
94+
95+
<-- collapse-4.vue -->
10396
```
10497

98+
### Trigger multiple collapse elements
10599
You can even collapse multiple `<b-collapse>` components via a single `v-b-toggle` by
106-
providing multiple target ids using modifers:
100+
providing multiple target IDs using modifers:
107101

108102
```html
109-
<b-btn v-b-toggle.collapse1.collapse2>Toggle Collapse 1 and 2</b-btn>
103+
<div>
104+
<!-- Single button triggers two b-collapse components -->
105+
<b-btn v-b-toggle.collapseA.collapseB>Toggle Both Collapse A and B</b-btn>
110106

111-
<!-- elements to collapse -->
112-
<b-collapse id="collapse1">
107+
<!-- elements to collapse -->
108+
<b-collapse id="collapsA" class="mt-2">
113109
<b-card>
114-
I am collapsable content 1!
110+
I am collapsable content A!
115111
</b-card>
116-
</b-collapse>
117-
<b-collapse id="collapse2">
112+
</b-collapse>
113+
<b-collapse id="collapseB" class="mt-2">
118114
<b-card>
119-
I am collapsable content 2!
115+
I am collapsable content B!
120116
</b-card>
121-
</b-collapse>
117+
</b-collapse>
118+
</div>
119+
120+
<!-- collapse-mult-1.vue -->
122121
```
123122

124123

125-
### Accordion Support
124+
## Accordion Support
126125

127126
Turn a group of `<b-collapse>` components into an accordion by supplying
128127
an accordion group identifier via the `accordion` prop:
129128

130129
```html
131-
<b-btn block v-b-toggle.collapse1>Collapsible Group 1</b-btn>
132-
<b-collapse id="collapse1" accordion="my-accordion" visible>
133-
<b-card>
134-
Accordion Panel 1<br>
135-
I start opened because <code>visible</code> is <code>true</code>
136-
</b-card>
137-
</b-collapse>
138-
<b-btn block class="mt-2" v-b-toggle.collapse2>Collapsible Group 2</b-btn>
139-
<b-collapse id="collapse2" accordion="my-accordion">
140-
<b-card>
141-
Accordion Panel 2
142-
</b-card>
143-
</b-collapse>
144-
<b-btn block class="mt-2" v-b-toggle.collapse3>Collapsible Group 3</b-btn>
145-
<b-collapse id="collapse3" accordion="my-accordion">
146-
<b-card>
147-
Accordion Panel 3
148-
</b-card>
149-
</b-collapse>
130+
<div>
131+
<b-card no-body>
132+
<b-card-header class="p-1">
133+
<b-btn block v-b-toggle.accordion1 variant="info">Accordion 1</b-btn>
134+
</b-card-header>
135+
<b-collapse id="accordion1" visible accordion="my-accordion">
136+
<b-card-body>
137+
<p class="card-text">
138+
I start opened because <code>visible</code> is <code>true</code>
139+
</p>
140+
<p class="card-text">
141+
Anim pariatur cliche reprehenderit, enim eiusmod high life accusamus terry
142+
richardson ad squid. 3 wolf moon officia aute, non cupidatat skateboard dolor
143+
brunch. Food truck quinoa nesciunt laborum eiusmod. Brunch 3 wolf moon
144+
tempor, sunt aliqua put a bird on it squid single-origin coffee nulla
145+
assumenda shoreditch et. Nihil anim keffiyeh helvetica, craft beer labore
146+
wes anderson cred nesciunt sapiente ea proident. Ad vegan excepteur butcher
147+
vice lomo. Leggings occaecat craft beer farm-to-table, raw denim aesthetic
148+
synth nesciunt you probably haven't heard of them accusamus labore VHS.
149+
</p>
150+
</b-card-body>
151+
</b-collapse>
152+
<b-card-header class="p-1">
153+
<b-btn block v-b-toggle.accordion2 variant="info">Accordion 2</b-btn>
154+
</b-card-header>
155+
<b-collapse id="accordion2" accordion="my-accordion">
156+
<b-card-body>
157+
<p class="card-text">
158+
Anim pariatur cliche reprehenderit, enim eiusmod high life accusamus terry
159+
richardson ad squid. 3 wolf moon officia aute, non cupidatat skateboard dolor
160+
brunch. Food truck quinoa nesciunt laborum eiusmod. Brunch 3 wolf moon
161+
tempor, sunt aliqua put a bird on it squid single-origin coffee nulla
162+
assumenda shoreditch et. Nihil anim keffiyeh helvetica, craft beer labore
163+
wes anderson cred nesciunt sapiente ea proident. Ad vegan excepteur butcher
164+
vice lomo. Leggings occaecat craft beer farm-to-table, raw denim aesthetic
165+
synth nesciunt you probably haven't heard of them accusamus labore VHS.
166+
</p>
167+
</b-card-body>
168+
</b-collapse>
169+
<b-card-header class="p-1">
170+
<b-btn block v-b-toggle.accordion3 variant="info">Accordion 3</b-btn>
171+
</b-card-header>
172+
<b-collapse id="accordion3" accordion="my-accordion">
173+
<b-card-body>
174+
<p class="card-text">
175+
Anim pariatur cliche reprehenderit, enim eiusmod high life accusamus terry
176+
richardson ad squid. 3 wolf moon officia aute, non cupidatat skateboard dolor
177+
brunch. Food truck quinoa nesciunt laborum eiusmod. Brunch 3 wolf moon
178+
tempor, sunt aliqua put a bird on it squid single-origin coffee nulla
179+
assumenda shoreditch et. Nihil anim keffiyeh helvetica, craft beer labore
180+
wes anderson cred nesciunt sapiente ea proident. Ad vegan excepteur butcher
181+
vice lomo. Leggings occaecat craft beer farm-to-table, raw denim aesthetic
182+
synth nesciunt you probably haven't heard of them accusamus labore VHS.
183+
</p>
184+
</b-card-body>
185+
</b-collapse>
186+
</b-card>
187+
</div>
188+
189+
<!-- accordion-1.vue -->
150190
```
151191

152192
**Notes:**
153-
- If using the `v-model` feature of `<b-collaspe>` in accordion mode, do not
154-
bind the `v-model` or `visible` of all the collapses in the accordion group to the same variable.
193+
- If using the `v-model` feature of `<b-collaspe>` in accordion mode, do not bind the
194+
`v-model` or `visible` prop of all the collapses in the accordion group to the same variable!
155195
- Ensure, at most, only one `<b-collapse>` in the accordion group has the `visible`
156196
prop and/or `v-model` set to `true`.
157197

158-
### Accessibility
159-
The `v-b-toggle` directive will automatically add the ARIA attributes `aria-controls` and `aria-expanded`
160-
to the component that the directive appears on. `aria-expanded` will reflect the state of
161-
the tartget `<b-collapse>` component, while `aria-controls` will be set to the ID(s)
162-
of the target `<b-collapse>` component(s).
163198

199+
## Hiding and showing content in the toggle button based on collapse state
200+
When using the `v-b-toggle` directive, the class `collapsed` will automatically be placed
201+
on the trigger element when the collapse is closed, and removed when open. You can
202+
use this class to display or hide content within the togger via custom CSS:
203+
204+
**Example HTML markup:**
205+
```html
206+
<b-btn v-b-toggle.myCollapse>
207+
<span class="when-opened">Close</span>
208+
<span class="when-closed">Open</span>
209+
My Collapse
210+
</b-btn>
211+
<b-collapse id="myCollapse">
212+
<!-- content here -->
213+
</b-collapse>
214+
```
215+
**Example Custom CSS:**
216+
```css
217+
.collapsed > .when-opened,
218+
:not(.collapsed) > .when-closed {
219+
display: none;
220+
}
221+
```
222+
223+
224+
## Accessibility
225+
226+
The `v-b-toggle` directive will automatically add the ARIA attributes `aria-controls` and `aria-expanded`
227+
to the component that the directive appears on (as well as add the class `collapsed` when not expanded).
228+
`aria-expanded` will reflect the state of the tartget `<b-collapse>` component, while `aria-controls`
229+
will be set to the ID(s) of the target `<b-collapse>` component(s).
230+
231+
If using `v-model` to set the visible state instead of the directive `v-b-toggle`, you will be
232+
required to, on the toggle element, add and control the attributes/class yourself.
233+
234+
While the `v-b-toggle` directive can be placed on almost any HTML element or Vue component, it is
235+
reccomended to use a button or link (or similar component) to act as your toggler. Otherwise your
236+
trigger elements may be inaccessible to keyboard or screen reader users. If you do place them on
237+
something other than a button or link (or similar component), you should add the attributes
238+
`tabindex="0"` and `role="button"` to allow users of assistive technology to reach your
239+
trigger element.

0 commit comments

Comments
 (0)