Skip to main content Skip to docs navigation

Dropdowns

Alterna la visibilidad de superposiciones contextuales para mostrar listas de enlaces y más con el complemento desplegable Bootstrap.

¿Qué es Dropdown?

Los menús desplegables son superposiciones contextuales que se pueden alternar (su visibilidad) para mostrar listas de enlaces y más. Se hacen interactivos con dropdown, el complemento JavaScript incluido de Bootstrap. Se alternan al hacer clic, no al pasar el mouse; esta es una decisión de diseño intencional.

Los menús desplegables se basan en una biblioteca de terceros, Popper, que proporciona posicionamiento dinámico y detección de viewport. Asegúrate de incluir popper.min.js antes del JavaScript de Bootstrap o usa bootstrap.bundle.min.js / bootstrap.bundle.js que contiene Popper. Popper no se usa para posicionar los menús desplegables en las barras de navegación, ya que no se requiere un posicionamiento dinámico.

Accesibilidad

El estándar WAI ARIA define un role="menu" widget actual, pero esto es específico para menús similares a aplicaciones que activan acciones o funciones. Los menús ARIA solo pueden contener elementos de menú, elementos de menú de casillas de verificación, elementos de menú de botones radio, grupos de botones radio y submenús.

Los menús desplegables de Bootstrap, por otro lado, están diseñados para ser genéricos y aplicables a una variedad de situaciones y estructuras de marcado. Por ejemplo, es posible crear menús desplegables que contengan entradas adicionales y controles de formulario, como campos de búsqueda o formularios de inicio de sesión. Por esta razón, Bootstrap no espera (ni agrega automáticamente) ninguno de los atributos role y aria- requeridos para los verdaderos menús ARIA. Los autores tendrán que incluir ellos mismos estos atributos más específicos.

Sin embargo, Bootstrap agrega soporte incorporado para la mayoría de las interacciones estándar del menú del teclado, como la capacidad de moverse a través de elementos individuales .dropdown-item usando las teclas de flecha del teclado y cerrar el menú con la tecla ESC .

Ejemplos

Envuelve el elemento conmutador del menú desplegable (tu botón o enlace) y el menú desplegable dentro de .dropdown, u otro elemento que declare position: relative;. Los menús desplegables se pueden activar desde los elementos <a> o <button> para adaptarse mejor a tus necesidades potenciales. Los ejemplos que se muestran aquí usan elementos semánticos <ul> cuando corresponde, pero se admite el marcado personalizado.

Botón único

Cualquier .btn individual se puede convertir en un menú desplegable con algunos cambios de marcado. Así es como puedes ponerlos a trabajar con cualquiera de los elementos <button>:

<div class="dropdown">
  <button class="btn btn-secondary dropdown-toggle" type="button" id="dropdownMenuButton1" data-bs-toggle="dropdown" aria-expanded="false">
    Botón Dropdown
  </button>
  <ul class="dropdown-menu" aria-labelledby="dropdownMenuButton1">
    <li><a class="dropdown-item" href="#">Acción</a></li>
    <li><a class="dropdown-item" href="#">Otra acción</a></li>
    <li><a class="dropdown-item" href="#">Algo más aqui</a></li>
  </ul>
</div>

Y con elementos <a>:

<div class="dropdown">
  <a class="btn btn-secondary dropdown-toggle" href="#" role="button" id="dropdownMenuLink" data-bs-toggle="dropdown" aria-expanded="false">
    Enlace Dropdown
  </a>

  <ul class="dropdown-menu" aria-labelledby="dropdownMenuLink">
    <li><a class="dropdown-item" href="#">Acción</a></li>
    <li><a class="dropdown-item" href="#">Otra acción</a></li>
    <li><a class="dropdown-item" href="#">Algo más aqui</a></li>
  </ul>
</div>

La mejor parte es que también puedes hacer esto con cualquier variante de botón:

<!-- Example single danger button -->
<div class="btn-group">
  <button type="button" class="btn btn-danger dropdown-toggle" data-bs-toggle="dropdown" aria-expanded="false">
    Acción
  </button>
  <ul class="dropdown-menu">
    <li><a class="dropdown-item" href="#">Acción</a></li>
    <li><a class="dropdown-item" href="#">Otra acción</a></li>
    <li><a class="dropdown-item" href="#">Algo más aqui</a></li>
    <li><hr class="dropdown-divider"></li>
    <li><a class="dropdown-item" href="#">Enlace separado</a></li>
  </ul>
</div>

Botón dividido

Del mismo modo, crea menús desplegables de botones divididos con prácticamente el mismo marcado que los menús desplegables de un solo botón, pero con la adición de .dropdown-toggle-split en el lado del botón de despliegue.

Usamos esta clase adicional para reducir el padding horizontal a cada lado del símbolo de despliegue (flecha hacia abajo) en un 25% y eliminamos el margin-left que se agrega para los menús desplegables de botones normales. Esos cambios adicionales mantienen el símbolo de despliegue centrado en el botón de división y brindan un área de impacto de tamaño más apropiado al lado del botón principal.

<!-- Example split danger button -->
<div class="btn-group">
  <button type="button" class="btn btn-danger">Acción</button>
  <button type="button" class="btn btn-danger dropdown-toggle dropdown-toggle-split" data-bs-toggle="dropdown" aria-expanded="false">
    <span class="visually-hidden">Toggle Dropdown</span>
  </button>
  <ul class="dropdown-menu">
    <li><a class="dropdown-item" href="#">Acción</a></li>
    <li><a class="dropdown-item" href="#">Otra acción</a></li>
    <li><a class="dropdown-item" href="#">Algo más aqui</a></li>
    <li><hr class="dropdown-divider"></li>
    <li><a class="dropdown-item" href="#">Enlace separado</a></li>
  </ul>
</div>

Dimensionamiento

Los menús desplegables de botones funcionan con botones de todos los tamaños, incluidos los botones desplegables predeterminados y divididos.

<!-- Large button groups (default and split) -->
<div class="btn-group">
  <button class="btn btn-secondary btn-lg dropdown-toggle" type="button" data-bs-toggle="dropdown" aria-expanded="false">
    Botón grande
  </button>
  <ul class="dropdown-menu">
    ...
  </ul>
</div>
<div class="btn-group">
  <button class="btn btn-secondary btn-lg" type="button">
    Botón grande dividido
  </button>
  <button type="button" class="btn btn-lg btn-secondary dropdown-toggle dropdown-toggle-split" data-bs-toggle="dropdown" aria-expanded="false">
    <span class="visually-hidden">Toggle Dropdown</span>
  </button>
  <ul class="dropdown-menu">
    ...
  </ul>
</div>
<div class="btn-group">
  <button class="btn btn-secondary btn-sm dropdown-toggle" type="button" data-bs-toggle="dropdown" aria-expanded="false">
    Botón pequeño
  </button>
  <ul class="dropdown-menu">
    ...
  </ul>
</div>
<div class="btn-group">
  <button class="btn btn-secondary btn-sm" type="button">
    Botón pequeño dividido
  </button>
  <button type="button" class="btn btn-sm btn-secondary dropdown-toggle dropdown-toggle-split" data-bs-toggle="dropdown" aria-expanded="false">
    <span class="visually-hidden">Toggle Dropdown</span>
  </button>
  <ul class="dropdown-menu">
    ...
  </ul>
</div>

Dark dropdowns

Opta por menús desplegables más oscuros para que coincidan con una barra de navegación oscura o un estilo personalizado agregando .dropdown-menu-dark en un .dropdown-menu existente. No se requieren cambios en los elementos desplegables.

<div class="dropdown">
  <button class="btn btn-secondary dropdown-toggle" type="button" id="dropdownMenuButton2" data-bs-toggle="dropdown" aria-expanded="false">
    Botón Dropdown
  </button>
  <ul class="dropdown-menu dropdown-menu-dark" aria-labelledby="dropdownMenuButton2">
    <li><a class="dropdown-item active" href="#">Acción</a></li>
    <li><a class="dropdown-item" href="#">Otra acción</a></li>
    <li><a class="dropdown-item" href="#">Algo más aqui</a></li>
    <li><hr class="dropdown-divider"></li>
    <li><a class="dropdown-item" href="#">Enlace separado</a></li>
  </ul>
</div>

Y ponlo en uso en una barra de navegación:

<nav class="navbar navbar-expand-lg navbar-dark bg-dark">
  <div class="container-fluid">
    <a class="navbar-brand" href="#">Navbar</a>
    <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbarNavDarkDropdown" aria-controls="navbarNavDarkDropdown" aria-expanded="false" aria-label="Toggle navigation">
      <span class="navbar-toggler-icon"></span>
    </button>
    <div class="collapse navbar-collapse" id="navbarNavDarkDropdown">
      <ul class="navbar-nav">
        <li class="nav-item dropdown">
          <a class="nav-link dropdown-toggle" href="#" id="navbarDarkDropdownMenuLink" role="button" data-bs-toggle="dropdown" aria-expanded="false">
            Dropdown
          </a>
          <ul class="dropdown-menu dropdown-menu-dark" aria-labelledby="navbarDarkDropdownMenuLink">
            <li><a class="dropdown-item" href="#">Acción</a></li>
            <li><a class="dropdown-item" href="#">Otra acción</a></li>
            <li><a class="dropdown-item" href="#">Algo más aqui</a></li>
          </ul>
        </li>
      </ul>
    </div>
  </div>
</nav>

Direcciones

RTL

Las direcciones se reflejan cuando se usa Bootstrap en RTL, lo que significa que .dropstart aparecerá en el lado derecho.

Dropup

Activa los menús desplegables sobre los elementos agregando .dropup al elemento padre.

<!-- Default dropup button -->
<div class="btn-group dropup">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-bs-toggle="dropdown" aria-expanded="false">
    Dropup
  </button>
  <ul class="dropdown-menu">
    <!-- Dropdown menu links -->
  </ul>
</div>

<!-- Split dropup button -->
<div class="btn-group dropup">
  <button type="button" class="btn btn-secondary">
    Dropup dividido
  </button>
  <button type="button" class="btn btn-secondary dropdown-toggle dropdown-toggle-split" data-bs-toggle="dropdown" aria-expanded="false">
    <span class="visually-hidden">Toggle Dropdown</span>
  </button>
  <ul class="dropdown-menu">
    <!-- Dropdown menu links -->
  </ul>
</div>

Dropend

Activa los menús desplegables a la derecha de los elementos agregando .dropend al elemento padre.

<!-- Default dropend button -->
<div class="btn-group dropend">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-bs-toggle="dropdown" aria-expanded="false">
    Dropend
  </button>
  <ul class="dropdown-menu">
    <!-- Dropdown menu links -->
  </ul>
</div>

<!-- Split dropend button -->
<div class="btn-group dropend">
  <button type="button" class="btn btn-secondary">
    Dropend dividido
  </button>
  <button type="button" class="btn btn-secondary dropdown-toggle dropdown-toggle-split" data-bs-toggle="dropdown" aria-expanded="false">
    <span class="visually-hidden">Toggle Dropend</span>
  </button>
  <ul class="dropdown-menu">
    <!-- Dropdown menu links -->
  </ul>
</div>

Dropstart

Activa los menús desplegables a la izquierda de los elementos agregando .dropstart al elemento padre.

<!-- Default dropstart button -->
<div class="btn-group dropstart">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-bs-toggle="dropdown" aria-expanded="false">
    Dropstart
  </button>
  <ul class="dropdown-menu">
    <!-- Dropdown menu links -->
  </ul>
</div>

<!-- Split dropstart button -->
<div class="btn-group">
  <div class="btn-group dropstart" role="group">
    <button type="button" class="btn btn-secondary dropdown-toggle dropdown-toggle-split" data-bs-toggle="dropdown" aria-expanded="false">
      <span class="visually-hidden">Toggle Dropstart</span>
    </button>
    <ul class="dropdown-menu">
      <!-- Dropdown menu links -->
    </ul>
  </div>
  <button type="button" class="btn btn-secondary">
    Dropstart dividido
  </button>
</div>

Elementos de menú

Puedes usar los elementos <a> o <button> como elementos desplegables.

<div class="dropdown">
  <button class="btn btn-secondary dropdown-toggle" type="button" id="dropdownMenu2" data-bs-toggle="dropdown" aria-expanded="false">
    Dropdown
  </button>
  <ul class="dropdown-menu" aria-labelledby="dropdownMenu2">
    <li><button class="dropdown-item" type="button">Acción</button></li>
    <li><button class="dropdown-item" type="button">Otra acción</button></li>
    <li><button class="dropdown-item" type="button">Algo más aqui</button></li>
  </ul>
</div>

También puedes crear elementos desplegables no interactivos con .dropdown-item-text. Siéntete libre de diseñar más con CSS personalizado o utilidades de texto.

<ul class="dropdown-menu">
  <li><span class="dropdown-item-text">Texto del elemento Dropdown</span></li>
  <li><a class="dropdown-item" href="#">Acción</a></li>
  <li><a class="dropdown-item" href="#">Otra acción</a></li>
  <li><a class="dropdown-item" href="#">Algo más aqui</a></li>
</ul>

Active

Agrega .active a los elementos en el menú desplegable para mostrarlos como activos. Para transmitir el estado active a las tecnologías de asistencia, usa el atributo aria-current — usando el valor page para la página actual, o true para el elemento actual en un conjunto.

<ul class="dropdown-menu">
  <li><a class="dropdown-item" href="#">Enlace regular</a></li>
  <li><a class="dropdown-item active" href="#" aria-current="true">Enlace activo</a></li>
  <li><a class="dropdown-item" href="#">Otro enlace</a></li>
</ul>

Deshabilitado

Agrega .disabled a los elementos en el menú desplegable para mostrarlos como deshabilitados.

<ul class="dropdown-menu">
  <li><a class="dropdown-item" href="#">Enlace regular</a></li>
  <li><a class="dropdown-item disabled">Enlace deshabilitado</a></li>
  <li><a class="dropdown-item" href="#">Otro enlace</a></li>
</ul>

Alineación del menú

De forma predeterminada, un menú desplegable se coloca automáticamente al 100% desde la parte superior y a lo largo del lado izquierdo de su elemento padre. Puedes cambiar esto con las clases direccionales .drop*, pero también puedes controlarlas con clases modificadoras adicionales.

Agrega .dropdown-menu-end a un .dropdown-menu para alinear a la derecha el menú desplegable. Las direcciones se reflejan cuando se usa Bootstrap en RTL, lo que significa que .dropdown-menu-end aparecerá en el lado izquierdo.

¡Cuidado! Los menús desplegables se posicionan gracias a Popper, excepto cuando están contenidos en una barra de navegación.
<div class="btn-group">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-bs-toggle="dropdown" aria-expanded="false">
    Ejemplo de menú alineado a la derecha
  </button>
  <ul class="dropdown-menu dropdown-menu-end">
    <li><button class="dropdown-item" type="button">Acción</button></li>
    <li><button class="dropdown-item" type="button">Otra acción</button></li>
    <li><button class="dropdown-item" type="button">Algo más aqui</button></li>
  </ul>
</div>

Alineación responsive

Si deseas utilizar la alineación responsive, deshabilita el posicionamiento dinámico agregando el atributo data-bs-display="static" y usa las clases de variación responsive.

Para alinear a la derecha el menú desplegable con el breakpoint dado o más grande, agrea .dropdown-menu{-sm|-md|-lg|-xl|-xxl}-end.

<div class="btn-group">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-bs-toggle="dropdown" data-bs-display="static" aria-expanded="false">
    Alineado a la izquierda pero alineado a la derecha cuando la pantalla es grande
  </button>
  <ul class="dropdown-menu dropdown-menu-lg-end">
    <li><button class="dropdown-item" type="button">Acción</button></li>
    <li><button class="dropdown-item" type="button">Otra acción</button></li>
    <li><button class="dropdown-item" type="button">Algo más aqui</button></li>
  </ul>
</div>

Para alinear a la izquierda el menú desplegable con el breakpoint dado o más grande, agrega .dropdown-menu-end y .dropdown-menu{-sm|-md|-lg|-xl|-xxl}-start.

<div class="btn-group">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-bs-toggle="dropdown" data-bs-display="static" aria-expanded="false">
    Alineado a la derecha pero alineado a la izquierda cuando la pantalla es grande
  </button>
  <ul class="dropdown-menu dropdown-menu-end dropdown-menu-lg-start">
    <li><button class="dropdown-item" type="button">Acción</button></li>
    <li><button class="dropdown-item" type="button">Otra acción</button></li>
    <li><button class="dropdown-item" type="button">Algo más aqui</button></li>
  </ul>
</div>

Ten en cuenta que no necesitas agregar un atributo data-bs-display="static" a los botones desplegables en las barras de navegación, ya que Popper no se usa en las barras de navegación.

Opciones de alineación

Tomando la mayoría de las opciones que se muestran arriba, aquí hay una pequeña demostración de varias opciones de alineación de dropdown en un solo lugar.

<div class="btn-group">
  <button class="btn btn-secondary dropdown-toggle" type="button" id="dropdownMenuButton" data-bs-toggle="dropdown" aria-expanded="false">
    Dropdown
  </button>
  <ul class="dropdown-menu" aria-labelledby="dropdownMenuButton">
    <li><a class="dropdown-item" href="#">Opción del menú</a></li>
    <li><a class="dropdown-item" href="#">Opción del menú</a></li>
    <li><a class="dropdown-item" href="#">Opción del menú</a></li>
  </ul>
</div>

<div class="btn-group">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-bs-toggle="dropdown" aria-expanded="false">
    Menú alineado a la derecha
  </button>
  <ul class="dropdown-menu dropdown-menu-end">
    <li><a class="dropdown-item" href="#">Opción del menú</a></li>
    <li><a class="dropdown-item" href="#">Opción del menú</a></li>
    <li><a class="dropdown-item" href="#">Opción del menú</a></li>
  </ul>
</div>

<div class="btn-group">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-bs-toggle="dropdown" data-bs-display="static" aria-expanded="false">
    Alineado a la izquierda, alineado a la derecha lg
  </button>
  <ul class="dropdown-menu dropdown-menu-lg-end">
    <li><a class="dropdown-item" href="#">Opción del menú</a></li>
    <li><a class="dropdown-item" href="#">Opción del menú</a></li>
    <li><a class="dropdown-item" href="#">Opción del menú</a></li>
  </ul>
</div>

<div class="btn-group">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-bs-toggle="dropdown" data-bs-display="static" aria-expanded="false">
    Alineado a la derecha, alineado a la izquierda lg
  </button>
  <ul class="dropdown-menu dropdown-menu-end dropdown-menu-lg-start">
    <li><a class="dropdown-item" href="#">Opción del menú</a></li>
    <li><a class="dropdown-item" href="#">Opción del menú</a></li>
    <li><a class="dropdown-item" href="#">Opción del menú</a></li>
  </ul>
</div>

<div class="btn-group dropstart">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-bs-toggle="dropdown" aria-expanded="false">
    Dropstart
  </button>
  <ul class="dropdown-menu">
    <li><a class="dropdown-item" href="#">Opción del menú</a></li>
    <li><a class="dropdown-item" href="#">Opción del menú</a></li>
    <li><a class="dropdown-item" href="#">Opción del menú</a></li>
  </ul>
</div>

<div class="btn-group dropend">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-bs-toggle="dropdown" aria-expanded="false">
    Dropend
  </button>
  <ul class="dropdown-menu">
    <li><a class="dropdown-item" href="#">Opción del menú</a></li>
    <li><a class="dropdown-item" href="#">Opción del menú</a></li>
    <li><a class="dropdown-item" href="#">Opción del menú</a></li>
  </ul>
</div>

<div class="btn-group dropup">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-bs-toggle="dropdown" aria-expanded="false">
    Dropup
  </button>
  <ul class="dropdown-menu">
    <li><a class="dropdown-item" href="#">Opción del menú</a></li>
    <li><a class="dropdown-item" href="#">Opción del menú</a></li>
    <li><a class="dropdown-item" href="#">Opción del menú</a></li>
  </ul>
</div>

Contenido del menú

Encabezados

Agrega un encabezado para etiquetar secciones de acciones en cualquier menú desplegable.

<ul class="dropdown-menu">
  <li><h6 class="dropdown-header">Encabezado del dropdown</h6></li>
  <li><a class="dropdown-item" href="#">Acción</a></li>
  <li><a class="dropdown-item" href="#">Otra acción</a></li>
</ul>

Divisores

Separa los grupos de elementos de menú relacionados con un divisor.

<ul class="dropdown-menu">
  <li><a class="dropdown-item" href="#">Acción</a></li>
  <li><a class="dropdown-item" href="#">Otra acción</a></li>
  <li><a class="dropdown-item" href="#">Algo más aqui</a></li>
  <li><hr class="dropdown-divider"></li>
  <li><a class="dropdown-item" href="#">Enlace separado</a></li>
</ul>

Texto

Coloca cualquier texto de forma libre dentro de un menú desplegable con texto y usa las utilidades de espaciado. Ten en cuenta que probablemente necesitarás estilos de tamaño adicionales para restringir el ancho del menú.

<div class="dropdown-menu p-4 text-muted" style="max-width: 200px;">
  <p>
    Algunos ejemplos de texto que fluyen libremente dentro del menú desplegable.
  </p>
  <p class="mb-0">
    Y esto es más texto de ejemplo.
  </p>
</div>

Formularios

Coloca un formulario dentro de un menú desplegable, o conviértelo en un menú desplegable, y usa las utilidades de margen o padding para darle el espacio negativo que necesitas.

<div class="dropdown-menu">
  <form class="px-4 py-3">
    <div class="mb-3">
      <label for="exampleDropdownFormEmail1" class="form-label">Correo electrónico</label>
      <input type="email" class="form-control" id="exampleDropdownFormEmail1" placeholder="[email protected]">
    </div>
    <div class="mb-3">
      <label for="exampleDropdownFormPassword1" class="form-label">Contraseña</label>
      <input type="password" class="form-control" id="exampleDropdownFormPassword1" placeholder="Contraseña">
    </div>
    <div class="mb-3">
      <div class="form-check">
        <input type="checkbox" class="form-check-input" id="dropdownCheck">
        <label class="form-check-label" for="dropdownCheck">
          Recuérdame
        </label>
      </div>
    </div>
    <button type="submit" class="btn btn-primary">Ingresar</button>
  </form>
  <div class="dropdown-divider"></div>
  <a class="dropdown-item" href="#">¿Nuevo por aquí? Regístrate</a>
  <a class="dropdown-item" href="#">¿Se te olvidó tu contraseña?</a>
</div>
<form class="dropdown-menu p-4">
  <div class="mb-3">
    <label for="exampleDropdownFormEmail2" class="form-label">Correo electrónico</label>
    <input type="email" class="form-control" id="exampleDropdownFormEmail2" placeholder="[email protected]">
  </div>
  <div class="mb-3">
    <label for="exampleDropdownFormPassword2" class="form-label">Contraseña</label>
    <input type="password" class="form-control" id="exampleDropdownFormPassword2" placeholder="Contraseña">
  </div>
  <div class="mb-3">
    <div class="form-check">
      <input type="checkbox" class="form-check-input" id="dropdownCheck2">
      <label class="form-check-label" for="dropdownCheck2">
        Recuérdame
      </label>
    </div>
  </div>
  <button type="submit" class="btn btn-primary">Ingresar</button>
</form>

Opciones de dropdown

Usa data-bs-offset o data-bs-reference para cambiar la ubicación del menú desplegable.

<div class="d-flex">
  <div class="dropdown me-1">
    <button type="button" class="btn btn-secondary dropdown-toggle" id="dropdownMenuOffset" data-bs-toggle="dropdown" aria-expanded="false" data-bs-offset="10,20">
      Offset
    </button>
    <ul class="dropdown-menu" aria-labelledby="dropdownMenuOffset">
      <li><a class="dropdown-item" href="#">Acción</a></li>
      <li><a class="dropdown-item" href="#">Otra acción</a></li>
      <li><a class="dropdown-item" href="#">Algo más aqui</a></li>
    </ul>
  </div>
  <div class="btn-group">
    <button type="button" class="btn btn-secondary">Referencia</button>
    <button type="button" class="btn btn-secondary dropdown-toggle dropdown-toggle-split" id="dropdownMenuReference" data-bs-toggle="dropdown" aria-expanded="false" data-bs-reference="parent">
      <span class="visually-hidden">Toggle Dropdown</span>
    </button>
    <ul class="dropdown-menu" aria-labelledby="dropdownMenuReference">
      <li><a class="dropdown-item" href="#">Acción</a></li>
      <li><a class="dropdown-item" href="#">Otra acción</a></li>
      <li><a class="dropdown-item" href="#">Algo más aqui</a></li>
      <li><hr class="dropdown-divider"></li>
      <li><a class="dropdown-item" href="#">Enlace separado</a></li>
    </ul>
  </div>
</div>

Comportamiento de cierre automático

De forma predeterminada, el menú desplegable se cierra al hacer clic dentro o fuera del menú desplegable. Puedes usar la opción autoClose para cambiar este comportamiento del menú desplegable.

<div class="btn-group">
  <button class="btn btn-secondary dropdown-toggle" type="button" id="defaultDropdown" data-bs-toggle="dropdown" data-bs-auto-close="true" aria-expanded="false">
    Default dropdown
  </button>
  <ul class="dropdown-menu" aria-labelledby="defaultDropdown">
    <li><a class="dropdown-item" href="#">Opción del menú</a></li>
    <li><a class="dropdown-item" href="#">Opción del menú</a></li>
    <li><a class="dropdown-item" href="#">Opción del menú</a></li>
  </ul>
</div>

<div class="btn-group">
  <button class="btn btn-secondary dropdown-toggle" type="button" id="dropdownMenuClickableOutside" data-bs-toggle="dropdown" data-bs-auto-close="inside" aria-expanded="false">
    Se puede hacer clic afuera
  </button>
  <ul class="dropdown-menu" aria-labelledby="dropdownMenuClickableOutside">
    <li><a class="dropdown-item" href="#">Opción del menú</a></li>
    <li><a class="dropdown-item" href="#">Opción del menú</a></li>
    <li><a class="dropdown-item" href="#">Opción del menú</a></li>
  </ul>
</div>

<div class="btn-group">
  <button class="btn btn-secondary dropdown-toggle" type="button" id="dropdownMenuClickableInside" data-bs-toggle="dropdown" data-bs-auto-close="outside" aria-expanded="false">
    Se puede hacer clic en el interior
  </button>
  <ul class="dropdown-menu" aria-labelledby="dropdownMenuClickableInside">
    <li><a class="dropdown-item" href="#">Opción del menú</a></li>
    <li><a class="dropdown-item" href="#">Opción del menú</a></li>
    <li><a class="dropdown-item" href="#">Opción del menú</a></li>
  </ul>
</div>

<div class="btn-group">
  <button class="btn btn-secondary dropdown-toggle" type="button" id="dropdownMenuClickable" data-bs-toggle="dropdown" data-bs-auto-close="false" aria-expanded="false">
    Cierre manual
  </button>
  <ul class="dropdown-menu" aria-labelledby="dropdownMenuClickable">
    <li><a class="dropdown-item" href="#">Opción del menú</a></li>
    <li><a class="dropdown-item" href="#">Opción del menú</a></li>
    <li><a class="dropdown-item" href="#">Opción del menú</a></li>
  </ul>
</div>

Sass

Variables

Variables para todos los menús desplegables:

$dropdown-min-width:                10rem;
$dropdown-padding-x:                0;
$dropdown-padding-y:                .5rem;
$dropdown-spacer:                   .125rem;
$dropdown-font-size:                $font-size-base;
$dropdown-color:                    $body-color;
$dropdown-bg:                       $white;
$dropdown-border-color:             rgba($black, .15);
$dropdown-border-radius:            $border-radius;
$dropdown-border-width:             $border-width;
$dropdown-inner-border-radius:      subtract($dropdown-border-radius, $dropdown-border-width);
$dropdown-divider-bg:               $dropdown-border-color;
$dropdown-divider-margin-y:         $spacer * .5;
$dropdown-box-shadow:               $box-shadow;

$dropdown-link-color:               $gray-900;
$dropdown-link-hover-color:         shade-color($dropdown-link-color, 10%);
$dropdown-link-hover-bg:            $gray-200;

$dropdown-link-active-color:        $component-active-color;
$dropdown-link-active-bg:           $component-active-bg;

$dropdown-link-disabled-color:      $gray-500;

$dropdown-item-padding-y:           $spacer * .25;
$dropdown-item-padding-x:           $spacer;

$dropdown-header-color:             $gray-600;
$dropdown-header-padding:           $dropdown-padding-y $dropdown-item-padding-x;

Variables para el dark dropdown:

$dropdown-dark-color:               $gray-300;
$dropdown-dark-bg:                  $gray-800;
$dropdown-dark-border-color:        $dropdown-border-color;
$dropdown-dark-divider-bg:          $dropdown-divider-bg;
$dropdown-dark-box-shadow:          null;
$dropdown-dark-link-color:          $dropdown-dark-color;
$dropdown-dark-link-hover-color:    $white;
$dropdown-dark-link-hover-bg:       rgba($white, .15);
$dropdown-dark-link-active-color:   $dropdown-link-active-color;
$dropdown-dark-link-active-bg:      $dropdown-link-active-bg;
$dropdown-dark-link-disabled-color: $gray-500;
$dropdown-dark-header-color:        $gray-500;

Variables para los símbolos de despliegue (flecha) basados en CSS que indican la interactividad de un menú desplegable:

$caret-width:                 .3em;
$caret-vertical-align:        $caret-width * .85;
$caret-spacing:               $caret-width * .85;

Mixins

Los mixins se utilizan para generar los símbolos de despliegue basados en CSS y se pueden encontrar en scss/mixins/_caret.scss.

@mixin caret-down {
  border-top: $caret-width solid;
  border-right: $caret-width solid transparent;
  border-bottom: 0;
  border-left: $caret-width solid transparent;
}

@mixin caret-up {
  border-top: 0;
  border-right: $caret-width solid transparent;
  border-bottom: $caret-width solid;
  border-left: $caret-width solid transparent;
}

@mixin caret-end {
  border-top: $caret-width solid transparent;
  border-right: 0;
  border-bottom: $caret-width solid transparent;
  border-left: $caret-width solid;
}

@mixin caret-start {
  border-top: $caret-width solid transparent;
  border-right: $caret-width solid;
  border-bottom: $caret-width solid transparent;
}

@mixin caret($direction: down) {
  @if $enable-caret {
    &::after {
      display: inline-block;
      margin-left: $caret-spacing;
      vertical-align: $caret-vertical-align;
      content: "";
      @if $direction == down {
        @include caret-down();
      } @else if $direction == up {
        @include caret-up();
      } @else if $direction == end {
        @include caret-end();
      }
    }

    @if $direction == start {
      &::after {
        display: none;
      }

      &::before {
        display: inline-block;
        margin-right: $caret-spacing;
        vertical-align: $caret-vertical-align;
        content: "";
        @include caret-start();
      }
    }

    &:empty::after {
      margin-left: 0;
    }
  }
}

Uso

A través de atributos de datos o JavaScript, el complemento dropdown alterna el contenido oculto (menús desplegables) al alternar la clase .show en el .dropdown-menu padre. Se confía en el atributo data-bs-toggle="dropdown" para cerrar los menús desplegables a nivel de aplicación, por lo que es una buena idea usarlo siempre.

En los dispositivos táctiles, al abrir un menú desplegable se agregan controladores vacíos mouseover a los elementos secundarios inmediatos del elemento <body>. Este truco ciertamente feo es necesario para evitar una peculiaridad en la delegación de eventos de iOS, que de otro modo evitaría un toque en cualquier lugar fuera del menú desplegable active el código que cierra el menú desplegable. Una vez que se cierra el menú desplegable, se eliminan estos controladores “mouseover” vacíos adicionales.

A través de atributos de datos

Agrega data-bs-toggle="dropdown" a un enlace o botón para alternar un menú desplegable.

<div class="dropdown">
  <button id="dLabel" type="button" data-bs-toggle="dropdown" aria-expanded="false">
    Dropdown trigger
  </button>
  <ul class="dropdown-menu" aria-labelledby="dLabel">
    ...
  </ul>
</div>

A través de JavaScript

Llama a los menús desplegables a través de JavaScript:

var dropdownElementList = Array.prototype.slice.call(document.querySelectorAll('.dropdown-toggle'))
var dropdownList = dropdownElementList.map(function (dropdownToggleEl) {
  return new bootstrap.Dropdown(dropdownToggleEl)
})
data-bs-toggle="dropdown" todavía se requiere

Independientemente de si llamas a tu menú desplegable a través de JavaScript o en su lugar utilizas la API de datos, data-bs-toggle="dropdown" siempre debe estar presente en el elemento desencadenante del menú desplegable.

Opciones

Las opciones se pueden pasar a través de atributos de datos o JavaScript. Para los atributos de datos, agrega el nombre de la opción a data-bs-, como en data-bs-offset="". 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, en lugar de usar data-bs-autoClose="false", usa data-bs-auto-close="false".

Nombre Tipo Por defecto Descripción
boundary string | element 'clippingParents' Límite de restricción de desbordamiento del menú desplegable (se aplica solo al modificador preventOverflow de Popper). De forma predeterminada, es 'clippingParents' y puede aceptar una referencia HTMLElement (solo a través de JavaScript). Para obtener más información, consulta las detectOverflow docs de Popper.
reference string | element | object 'toggle' Elemento de referencia del menú desplegable. Acepta los valores de 'toggle', 'parent', una referencia HTMLElement o un objeto que proporciona getBoundingClientRect. Para obtener más información, consulta las documentos de construcción y documentos de elementos virtuales.
display string 'dynamic' Por defecto, usamos Popper para el posicionamiento dinámico. Deshabilita esto con static.
offset array | string | function [0, 2]

Desplazamiento del menú desplegable en relación con su objetivo. Puedes pasar una cadena en atributos de datos con valores separados por comas como: data-bs-offset="10,20"

Cuando se usa una función para determinar el desplazamiento, se llama con un objeto que contiene la ubicación del popper, la referencia y los rects del popper como su primer argumento. El nodo DOM del elemento desencadenante se pasa como segundo argumento. La función debe devolver una matriz con dos números: [skidding, distance].

Para obtener más información, consulta las documentos de compensación de Popper.

autoClose boolean | string true

Configura el comportamiento de cierre automático del menú desplegable:

  • true: el menú desplegable se cerrará haciendo clic fuera o dentro del menú desplegable.
  • false: el menú desplegable se cerrará haciendo clic en el botón de alternancia y llamando manualmente al método hide o toggle. (Tampoco se cerrará presionando la tecla esc)
  • 'inside': el menú desplegable se cerrará (solo) al hacer clic dentro del menú desplegable.
  • 'outside': el menú desplegable se cerrará (solo) al hacer clic fuera del menú desplegable.
popperConfig null | object | function null

Para cambiar la configuración predeterminada de Popper de Bootstrap, consulta Configuración de Popper.

Cuando se usa una función para crear la configuración Popper, se llama con un objeto que contiene la configuración Popper predeterminada de Bootstrap. Te ayuda a usar y fusionar el valor predeterminado con tu propia configuración. La función debe devolver un objeto de configuración para Popper.

Usando la función con popperConfig

var dropdown = new bootstrap.Dropdown(element, {
  popperConfig: function (defaultBsPopperConfig) {
    // var newPopperConfig = {...}
    // usa defaultBsPopperConfig si es necesario...
    // devuelve newPopperConfig
  }
})

Métodos

Método Descripción
toggle Alterna el menú desplegable de una barra de navegación determinada o navegación con pestañas.
show Muestra el menú desplegable de una barra de navegación determinada o navegación con pestañas.
hide Oculta el menú desplegable de una barra de navegación determinada o navegación con pestañas.
update Actualiza la posición del menú desplegable de un elemento.
dispose Destruye el menú desplegable de un elemento. (Elimina los datos almacenados en el elemento DOM)
getInstance Método estático que te permite obtener la instancia desplegable asociada a un elemento DOM, puedes usarlo así: bootstrap.Dropdown.getInstance(element)
getOrCreateInstance Método estático que devuelve una instancia desplegable asociada a un elemento DOM o crea una nueva en caso de que no se haya inicializado. Puedes usarlo así: bootstrap.Dropdown.getOrCreateInstance(element)

Eventos

Todos los eventos desplegables se activan en el elemento de alternancia y luego se expanden. Por lo tanto, también puedes agregar detectores de eventos en el elemento padre .dropdown-menu. Los eventos hide.bs.dropdown y hidden.bs.dropdown tienen una propiedad clickEvent (solo cuando el tipo de evento original es click) que contiene un objeto Event para el evento de clic.

Método Descripción
show.bs.dropdown Se activa inmediatamente cuando se llama al método de instancia show.
shown.bs.dropdown Se activa cuando el menú desplegable se ha hecho visible para el usuario y se han completado las transiciones de CSS.
hide.bs.dropdown Se activa inmediatamente cuando se llama al método de instancia hide.
hidden.bs.dropdown Se activa cuando el menú desplegable ha terminado de ocultarse para el usuario y se han completado las transiciones de CSS.
var myDropdown = document.getElementById('myDropdown')
myDropdown.addEventListener('show.bs.dropdown', function () {
  // hacer algo...
})