El componente Collapse de Bootstrap

Alterna la visibilidad del contenido en tu proyecto con algunas clases y nuestros complementos de JavaScript.

Cómo funciona el componente Collapse

El complemento JavaScript para contraer se utiliza para mostrar y ocultar contenido. Los botones o anclajes se utilizan como activadores que se asignan a elementos específicos que alterna. Colapsar un elemento animará el height desde su valor actual a 0. Dado cómo CSS maneja las animaciones, no puedes usar padding en un elemento .collapse. En su lugar, utiliza la clase como elemento envolvente independiente.

Ejemplo del componente Collapse

Haz clic en los botones a continuación para mostrar y ocultar otro elemento mediante cambios de clase:

• .collapse oculta contenido
• .collapsing se aplica durante las transiciones
• .collapse.show muestra contenido

Generalmente, recomendamos usar un <button> con el atributo data-bs-target. Aunque no se recomienda desde un punto de vista semántico, también puedes usar un enlace <a> con el atributo href (y un role="button"). En ambos casos, se requiere data-bs-toggle="collapse".

<p class="d-inline-flex gap-1">
    <a class="btn btn-primary" data-bs-toggle="collapse" href="#collapseExample" role="button"
        aria-expanded="false" aria-controls="collapseExample">
        Enlace con href
    </a>
    <button class="btn btn-primary" type="button" data-bs-toggle="collapse" data-bs-target="#collapseExample"
        aria-expanded="false" aria-controls="collapseExample">
        Botón con data-bs-target
    </button>
</p>
<div class="collapse" id="collapseExample">
    <div class="card card-body">
        Algún contenido de marcador de posición para el componente de colapso. Este panel está oculto de forma
        predeterminada, pero se revela cuando el usuario activa el activador correspondiente.
    </div>
</div>

Componente Collapse horizontal

El complemento de colapso admite el colapso horizontal. Agrea la clase modificadora .collapse-horizontal para realizar la transición del width en lugar de height y establece un width en el elemento hijo inmediato. Siéntete libre de escribir tu propio Sass personalizado, usar estilos en línea o usar nuestras utilidades de ancho.

<p>
    <button class="btn btn-primary" type="button" data-bs-toggle="collapse"
        data-bs-target="#collapseWidthExample" aria-expanded="false" aria-controls="collapseWidthExample">
        Alternar colapso a lo ancho
    </button>
</p>
<div style="min-height: 120px;">
    <div class="collapse collapse-horizontal" id="collapseWidthExample">
        <div class="card card-body" style="width: 300px;">
            Este es un contenido de marcador de posición para un colapso horizontal. Está oculto de forma
            predeterminada y se muestra cuando se activa.
        </div>
    </div>
</div>

Múltiples opciones y objetivos

Un elemento <button> o <a> puede mostrar y ocultar múltiples elementos haciendo referencia a ellos con un selector en su atributo data-bs-target o href. Por el contrario, varios elementos <button> o <a> pueden mostrar y ocultar el mismo elemento si cada uno de ellos hace referencia a él con su data-bs-target o href.

    <p class="d-inline-flex gap-1">
        <a class="btn btn-primary" data-bs-toggle="collapse" href="#multiCollapseExample1" role="button"
            aria-expanded="false" aria-controls="multiCollapseExample1">Alternar el primer elemento</a>
        <button class="btn btn-primary" type="button" data-bs-toggle="collapse"
            data-bs-target="#multiCollapseExample2" aria-expanded="false"
            aria-controls="multiCollapseExample2">Alternar segundo elemento</button>
        <button class="btn btn-primary" type="button" data-bs-toggle="collapse" data-bs-target=".multi-collapse"
            aria-expanded="false" aria-controls="multiCollapseExample1 multiCollapseExample2">Alterna ambos
            elementos</button>
    </p>
    <div class="row">
        <div class="col">
            <div class="collapse multi-collapse" id="multiCollapseExample1">
                <div class="card card-body">
                    Contenido de marcador de posición para el primer componente de colapso de este ejemplo de
                    colapso múltiple. Este panel está oculto de forma predeterminada, pero se revela cuando el
                    usuario activa el activador correspondiente.
                </div>
            </div>
        </div>
        <div class="col">
            <div class="collapse multi-collapse" id="multiCollapseExample2">
                <div class="card card-body">
                    Contenido de marcador de posición para el segundo componente de colapso de este ejemplo de
                    colapso múltiple. Este panel está oculto de forma predeterminada, pero se revela cuando el
                    usuario activa el activador correspondiente.
                </div>
            </div>
        </div>
    </div>

Accesibilidad del componente Collapse

Asegúrate de agregar aria-expanded al elemento de control. Este atributo transmite explícitamente el estado actual del elemento plegable vinculado al control a lectores de pantalla y tecnologías de asistencia similares. Si el elemento plegable está cerrado de forma predeterminada, el atributo del elemento de control debe tener un valor de aria-expanded="false". Si has configurado el elemento plegable para que se abra de forma predeterminada usando la clase show, configura aria-expanded="true" en el control. El complemento alternará automáticamente este atributo en el control en función de si el elemento plegable se ha abierto o cerrado (a través de JavaScript, o porque el usuario activó otro elemento de control también vinculado al mismo elemento plegable). Si el elemento HTML del elemento de control no es un botón (por ejemplo, un <a> o <div>), el atributo role="button" debe agregarse al elemento.

Si tu elemento de control apunta a un único elemento plegable, es decir, el atributo data-bs-target apunta a un selector id, debes agregar el atributo aria-controls al elemento de control, que contiene el id del elemento plegable. Los lectores de pantalla modernos y tecnologías de asistencia similares utilizan este atributo para proporcionar a los usuarios accesos directos adicionales para navegar directamente al elemento plegable.

Ten en cuenta que la implementación actual de Bootstrap no cubre las diversas interacciones de teclado opcionales descritas en Patrón de acordeón de la Guía de prácticas de creación de ARIA, deberás incluirlos tú mismo con JavaScript personalizado.

Personalización del CSS del componente

Variables Sass generales relacionadas

scss/_variables.scss

$transition-collapse:         height .35s ease;
$transition-collapse-width:   width .35s ease;

Clases

Las clases de transición de collapse se pueden encontrar en scss/_transitions.scss ya que se comparten entre múltiples componentes (collapse y accordion).

scss/_transitions.scss

.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);
    }
}

Uso del componente Collapse

El complemento de colapso utiliza algunas clases para manejar el trabajo pesado:

• .collapse oculta el contenido
• .collapse.show muestra el contenido
• .collapsing se agrega cuando comienza la transición y se elimina cuando finaliza

Estas clases se pueden encontrar en _transitions.scss.

Vía atributos de datos

Simplemente agrega data-bs-toggle="collapse" y un data-bs-target al elemento para asignar automáticamente control de uno o más elementos plegables. El atributo data-bs-target acepta un selector CSS al que aplicar el colapso. Asegúrate de agregar la clase collapse al elemento plegable. Si deseas que se abra de forma predeterminada, agrega la clase adicional show.

Para agregar administración de grupos tipo acordeón a un área plegable, agrega el atributo de datos data-bs-parent="#selector". Consulta la página del acordeón para obtener más información.

Vía JavaScript

Habilitar manualmente con:

const collapseElementList = document.querySelectorAll('.collapse')
const collapseList = [...collapseElementList].map(collapseEl => new bootstrap.Collapse(collapseEl))

Opciones

Como las opciones se pueden pasar a través de atributos de datos o JavaScript, puedes agregar un nombre de opción a data-bs-, como en data-bs-animation="{value}". Asegúrate de cambiar el tipo de caso del nombre de la opción de “camelCase” a “kebab-case” al pasar las opciones a través de atributos de datos. Por ejemplo, utiliza data-bs-custom-class="beautifier" en lugar de data-bs-customClass="beautifier".

A partir de Bootstrap 5.2.0, todos los componentes admiten un atributo de datos experimental reservado data-bs-config que puede albergar datos simples de configuración del componente como una cadena JSON. Cuando un elemento tiene los atributos data-bs-config='{"delay":0, "title":123}' y data-bs-title="456", el valor final de title será 456 y los atributos de datos separados sobrescribirán los valores proporcionados en data-bs-config. Además, los atributos de datos existentes pueden albergar valores JSON como data-bs-delay='{"show":0,"hide":150}'.

El objeto de configuración final es el resultado combinado de data-bs-config, data-bs- y js object donde el último valor-clave dado sobrescribe los demás.

Métodos

Activa tu contenido como un elemento plegable. Acepta opciones opcionales object.

Puedes crear una instancia colapsada con el constructor, por ejemplo:

const bsCollapse = new bootstrap.Collapse('#myCollapse', {
    toggle: false
})

Eventos

La clase de colapso de Bootstrap expone algunos eventos para conectarse a la funcionalidad de colapso.

const myCollapsible = document.getElementById('myCollapsible')
myCollapsible.addEventListener('hidden.bs.collapse', event => {
    // do something...
})