Powered by NeGD | MeitY Government of India® UX4G
Collapse
Toggle the visibility of content across your project with a few classes and our JavaScript plugins.
How it works #
The JavaScript plugin for collapse
is used to reveal and conceal content. Triggers that are mapped to particular components you toggle are buttons or anchors. When an element is collapsed
, the height will animate from its current value to zero. There can be no use of padding on a collapse
element due to the way CSS handles animations
. Use the class as a stand-alone wrapper element instead.
prefers-reduced-motion
media query. See the reduced motion section of our accessibility documentation.Example #
To display and hide a different element by changing its class, click the buttons below:
- Content is hidden by
.collapse
. - Transitions are when collapse is used.
- Show content in collapse
Usage of a button with the data-bs-target
attribute is generally advised. Also utilize a link with the href property (and a role="button"
), albeit doing so is not advised from a semantic perspective. The data-bs-toggle="collapse"
is necessary in both situations.
<p>
<a class="btn btn-primary" data-bs-toggle="collapse" href="#collapseExample" role="button" aria-expanded="false" aria-controls="collapseExample">
Link with href
</a>
<button class="btn btn-primary" type="button" data-bs-toggle="collapse" data-bs-target="#collapseExample" aria-expanded="false" aria-controls="collapseExample">
Button with data-bs-target
</button>
</p>
<div class="collapse" id="collapseExample">
<div class="card card-body">
Some placeholder content for the collapse component. This panel is hidden by default but revealed when the user activates the relevant trigger.
</div>
</div>
RESULT
Horizontal #
Horizontal collapsing is also supported by the collapse plugin. Set a width on the immediate child element and add the .collapse-horizontal
modifier class to transition the width rather than the height. Welcome to use the width utilities, write unique Sass, or use inline styles.
min-height
set to avoid excessive repaints in our docs, this is not explicitly required. Only the width
on the child element is required.<p>
<button class="btn btn-primary" type="button" data-bs-toggle="collapse" data-bs-target="#collapseWidthExample" aria-expanded="false" aria-controls="collapseWidthExample">
Toggle width collapse
</button>
</p>
<div style="min-height: 120px;">
<div class="collapse collapse-horizontal" id="collapseWidthExample">
<div class="card card-body" style="width: 300px;">
This is some placeholder content for a horizontal collapse. It's hidden by default and shown when triggered.
</div>
</div>
</div>
RESULT
Multiple targets #
By referring them with a selector in its href or data-bs-target
property, a "button"
or "a"
can reveal and conceal several items. If each <button>
or references an element with its href or data-bs-target
attribute, the element can be shown and hidden.
<p>
<a class="btn btn-primary" data-bs-toggle="collapse" href="#multiCollapseExample1" role="button" aria-expanded="false" aria-controls="multiCollapseExample1">Toggle first element</a>
<button class="btn btn-primary" type="button" data-bs-toggle="collapse" data-bs-target="#multiCollapseExample2" aria-expanded="false" aria-controls="multiCollapseExample2">Toggle second element</button>
<button class="btn btn-primary" type="button" data-bs-toggle="collapse" data-bs-target=".multi-collapse" aria-expanded="false" aria-controls="multiCollapseExample1 multiCollapseExample2">Toggle both elements</button>
</p>
<div class="row">
<div class="col">
<div class="collapse multi-collapse" id="multiCollapseExample1">
<div class="card card-body">
Some placeholder content for the first collapse component of this multi-collapse example. This panel is hidden by default but revealed when the user activates the relevant trigger.
</div>
</div>
</div>
<div class="col">
<div class="collapse multi-collapse" id="multiCollapseExample2">
<div class="card card-body">
Some placeholder content for the second collapse component of this multi-collapse example. This panel is hidden by default but revealed when the user activates the relevant trigger.
</div>
</div>
</div>
</div>
RESULT
Accessibility #
Make sure the control element has aria-expanded
. This attribute explicitly communicates to screen readers and other assistive devices the current status of the collapsible element connected to the control. The control element's property should be set to aria-expanded="false"
if the collapsible element is closed by default. Set aria-expanded="true"
on the control if we've used the show class to have the collapsible element default to being open. Depending on whether the collapsible element has been opened or closed (through JavaScript, or because the user triggered another control element also related to the same collapsible element), the plugin will automatically toggle this attribute on the control. The attribute role="button"role="button"
should be applied to the control element if its HTML element is not a button (such as an a> or div>).
Adding the aria-controls
attribute to your control element, which contains the id of the collapsible element, is necessary if the control element is targeting just one collapsible element, as indicated by the data-bs-target
attribute pointing to an id selector. This attribute is used by contemporary screen readers and other assistive devices to give users more shortcuts to get to the collapsible element itself.
Write custom JavaScript to add the different optional keyboard interactions defined in the ARIA Authoring Practices Guide accordion pattern since UX4G's present implementation does not support them.
Sass #
Variables #
$transition-collapse: height .35s ease;
$transition-collapse-width: width .35s ease;
Classes #
SCS/_transitions
contains classes for collapse transitions.scss
because these are shared by both the collapse and accordion components.
.collapse {
&:not(.show) {
display: none;
}
}
.collapsing {
height: 0;
overflow: hidden;
@include transition($transition-collapse);
&.collapse-horizontal {
width: 0;
height: auto;
@include transition($transition-collapse-width);
}
}
Usage #
A few classes are used by the collapse plugin to carry out the labor-intensive tasks:
- The content is hidden by collapse
- Show collapse displays the information
- When the transition begins, collapse is added; when it ends, it is removed.
transitions.scss
contains these classes.
Via data attributes #
To automatically give control of one or more collapsible elements to the element, simply add data-bs-toggle="collapse"
and a data-bs-target
to the element. A CSS selector can be used with the data-bs-target
attribute to apply the collapse. Make sure to give the collapsible element the class collapse. To open by default, add the extra class show.
Add the data attribute data-bs-parent="#selector" to a collapsible section to enable group management that functions like an accordion. For more details, see the accordion page.
Via JavaScript #
Enable manually with:
const collapseElementList = document.querySelectorAll('.collapse')
const collapseList = [...collapseElementList].map(collapseEl => new bootstrap.Collapse(collapseEl))
Options #
Data-bs-animation
can have an option name appended to it, for example, data-bs-animation="value,"
since options can be provided through data attributes or JavaScript. When sending the choices via data attributes, be sure to modify the case type of the option name from "camelCase"
to "kebab-case."
Use data-bs-custom-class="beautifier"
as opposed to data-bs-customClass="beautifier,"
for instance.
Since UX4G 1.0.0, all components are compatible with the experimental reserved data attribute data-bs-config
, which can store a JSON string for basic component setting. When an element has the data-bs-config="delay":0
, "title":123"
and data-bs-title="456"
attributes, the final title value will be 456 and the individual data attributes will take precedence over the values specified on the data-bs-config
. Additionally, JSON variables like data-bs-delay='"show":0
, "hide":150"
can be stored in existing data attributes.
Name | Type | Default | Description |
---|---|---|---|
parent | selector, jQuery object, DOM element | false | If parent is provided, then all collapsible elements under the specified parent will be closed when this collapsible item is shown. (similar to traditional accordion behavior - this is dependent on the card class). The attribute has to be set on the target collapsible area. |
toggle | boolean | true | Toggles the collapsible element on invocation |
Methods #
Asynchronous methods and transitions ​
All API methods are asynchronous and start a transition. They return to the caller as soon as the transition is started but before it ends. In addition, a method call on a transitioning component will be ignored.
You can create a collapse instance with the constructor, for example:
const bsCollapse = new UX4G.Collapse('#myCollapse', {
toggle: false
})
Method | Description |
---|---|
dispose | Destroys an element’s collapse. (Removes stored data on the DOM element) |
getInstance | Static method which allows you to get the collapse instance associated to a DOM element, you can use it like this: UX4G.Collapse.getInstance(element) |
getOrCreateInstance | Static method which returns a collapse instance associated to a DOM element or create a new one in case it wasn’t initialized. You can use it like this: UX4G.Collapse.getOrCreateInstance(element) |
hide | Hides a collapsible element. Returns to the caller before the collapsible element has actually been hidden (e.g., before the hidden.bs.collapse event occurs). |
show | Shows a collapsible element. Returns to the caller before the collapsible element has actually been shown (e.g., before the shown.bs.collapse event occurs). |
toggle | Toggles a collapsible element to shown or hidden. Returns to the caller before the collapsible element has actually been shown or hidden (i.e. before the shown.bs.collapse or hidden.bs.collapse event occurs). |
Events #
UX4G’s collapse class exposes a few events for hooking into collapse functionality.
Method | Description |
---|---|
dispose | Destroys an element’s collapse. (Removes stored data on the DOM element) |
getInstance | Static method which allows you to get the collapse instance associated to a DOM element, you can use it like this: UX4G.Collapse.getInstance(element) |
getOrCreateInstance | Static method which returns a collapse instance associated to a DOM element or create a new one in case it wasn’t initialized. You can use it like this: UX4G.Collapse.getOrCreateInstance(element) |
hide | Hides a collapsible element. Returns to the caller before the collapsible element has actually been hidden (e.g., before the hidden.bs.collapse event occurs). |
show | Shows a collapsible element. Returns to the caller before the collapsible element has actually been shown (e.g., before the shown.bs.collapse event occurs). |
toggle | Toggles a collapsible element to shown or hidden. Returns to the caller before the collapsible element has actually been shown or hidden (i.e. before the shown.bs.collapse or hidden.bs.collapse event occurs). |