Ver en GitHub

JavaScript

Da vida a Bootstrap con nuestros plugins opcionales de JavaScript. Conoce cada plugin, nuestras opciones de API data y programática, y más.

On this page

Individual o compilado

Los plugins pueden incluirse individualmente (usando los js/dist/*.js individuales de Bootstrap), o todos a la vez usando bootstrap.js o el minificado bootstrap.min.js (no incluyas ambos).

Si usas un bundler (Webpack, Parcel, Vite…), puedes usar los archivos /js/dist/*.js que son compatibles con UMD.

Uso con frameworks de JavaScript

Si bien el CSS de Bootstrap puede usarse con cualquier framework, el JavaScript de Bootstrap no es totalmente compatible con frameworks de JavaScript como React, Vue y Angular que asumen conocimiento completo del DOM. Tanto Bootstrap como el framework pueden intentar mutar el mismo elemento DOM, resultando en errores como menús desplegables que se quedan atascados en la posición “abierta”.

Una mejor alternativa para quienes usan este tipo de frameworks es usar un paquete específico del framework en lugar de el JavaScript de Bootstrap. Aquí hay algunas de las opciones más populares:

React: React Bootstrap
Vue: BootstrapVue (actualmente solo soporta Vue 2 y Bootstrap 4)
Angular: ng-bootstrap

Uso de Bootstrap como módulo

¡Pruébalo tú mismo! Descarga el código fuente y la demo funcional para usar Bootstrap como módulo ES desde el repositorio twbs/examples. También puedes abrir el ejemplo en StackBlitz.

Proporcionamos una versión de Bootstrap construida como ESM (bootstrap.esm.js y bootstrap.esm.min.js) que te permite usar Bootstrap como módulo en el navegador, si tus navegadores objetivo lo soportan.

<script type="module">
  import { Toast } from 'bootstrap.esm.min.js'

  Array.from(document.querySelectorAll('.toast'))
    .forEach(toastNode => new Toast(toastNode))
</script>

En comparación con los bundlers de JS, usar ESM en el navegador requiere que uses la ruta completa y el nombre del archivo en lugar del nombre del módulo. Lee más sobre los módulos JS en el navegador. That’s why we use 'bootstrap.esm.min.js' instead of 'bootstrap' above. However, this is further complicated by our Popper dependency, which imports Popper into our JavaScript like so:

import * as Popper from "@popperjs/core"

Si pruebas esto tal cual, verás un error en la consola como el siguiente:

Uncaught TypeError: Failed to resolve module specifier "@popperjs/core". Relative references must start with either "/", "./", or "../".

Para solucionar esto, puedes usar un importmap para resolver los nombres arbitrarios de módulos a rutas completas. Si tus navegadores objetivo no soportan importmap, necesitarás usar el proyecto es-module-shims. Así es como funciona para Bootstrap y Popper:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.2.3/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-rbsA2VBKQhggwzxH7pPCaAqO46MgnOM80zW1RWuH61DGLwZJEdK2Kadq2F9CUG65" crossorigin="anonymous">
    <title>Hello, modularity!</title>
  </head>
  <body>
    <h1>Hello, modularity!</h1>
    <button id="popoverButton" type="button" class="btn btn-primary btn-lg" class="btn btn-lg btn-danger" data-bs-toggle="popover" title="ESM in Browser" data-bs-content="Bang!">Custom popover</button>

    <script async src="https://cdn.jsdelivr.net/npm/es-module-shims@1/dist/es-module-shims.min.js" crossorigin="anonymous"></script>
    <script type="importmap">
    {
      "imports": {
        "@popperjs/core": "https://cdn.jsdelivr.net/npm/@popperjs/core@2.11.6/dist/umd/popper.min.js",
        "bootstrap": "https://cdn.jsdelivr.net/npm/bootstrap@5.2.3/dist/js/bootstrap.esm.min.js"
      }
    }
    </script>
    <script type="module">
      import * as bootstrap from 'bootstrap'

      new bootstrap.Popover(document.getElementById('popoverButton'))
    </script>
  </body>
</html>

Dependencias

Algunos plugins y componentes CSS dependen de otros plugins. Si incluyes plugins individualmente, asegúrate de comprobar estas dependencias en la documentación.

Nuestros menús desplegables, popovers y tooltips también dependen de Popper.

Atributos data

Casi todos los plugins de Bootstrap pueden activarse y configurarse a través de HTML únicamente con atributos data (nuestra forma preferida de usar la funcionalidad JavaScript). Asegúrate de usar solo un conjunto de atributos data en un solo elemento (ej., no puedes activar un tooltip y un modal desde el mismo botón).

Como las opciones se pueden pasar vía atributos data o JavaScript, puedes añadir un nombre de opción a data-bs-, como en data-bs-animation="{value}". Asegúrate de cambiar el tipo de capitalización del nombre de la opción de “camelCase” a “kebab-case” al pasar las opciones vía atributos data. Por ejemplo, usa data-bs-custom-class="beautifier" en lugar de data-bs-customClass="beautifier".

A partir de Bootstrap 5.2.0, todos los componentes soportan un atributo data reservado experimental data-bs-config que puede albergar una configuración simple 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 data separados sobrescribirán los valores dados en data-bs-config. Además, los atributos data existentes pueden albergar valores JSON como data-bs-delay='{"show":0,"hide":150}'.

Selectores

Usamos los métodos nativos querySelector y querySelectorAll para consultar elementos del DOM por razones de rendimiento, así que debes usar selectores válidos. Si usas selectores especiales como collapse:Example, asegúrate de escaparlos.

Eventos

Bootstrap proporciona eventos personalizados para las acciones únicas de la mayoría de plugins. Generalmente, estos vienen en forma de infinitivo y participio - donde el infinitivo (ej. show) se dispara al inicio de un evento, y su forma de participio (ej. shown) se dispara al completar una acción.

Todos los eventos infinitivos proporcionan la funcionalidad preventDefault(). Esto da la capacidad de detener la ejecución de una acción antes de que comience. Devolver false desde un manejador de eventos también llamará automáticamente a preventDefault().

const myModal = document.querySelector('#myModal')

myModal.addEventListener('show.bs.modal', event => {
  if (!data) {
    return event.preventDefault() // stops modal from being shown
  }
})

API programática

Todos los constructores aceptan un objeto de opciones opcional o nada (lo cual inicia un plugin con su comportamiento predeterminado):

const myModalEl = document.querySelector('#myModal')

const modal = new bootstrap.Modal(myModalEl) // initialized with defaults

const configObject = { keyboard: false }
const modal1 = new bootstrap.Modal(myModalEl, configObject) // initialized with no keyboard

Si deseas obtener una instancia particular de un plugin, cada plugin expone un método getInstance. Por ejemplo, para recuperar una instancia directamente desde un elemento:

bootstrap.Popover.getInstance(myPopoverEl)

Este método devolverá null si no se ha iniciado una instancia sobre el elemento solicitado.

Alternativamente, getOrCreateInstance puede usarse para obtener la instancia asociada a un elemento DOM, o crear una nueva en caso de que no haya sido inicializada.

bootstrap.Popover.getOrCreateInstance(myPopoverEl, configObject)

En caso de que una instancia no haya sido inicializada, puede aceptar y usar un objeto de configuración opcional como segundo argumento.

Selectores CSS en constructores

Además de los métodos getInstance y getOrCreateInstance, todos los constructores de plugins pueden aceptar un elemento DOM o un selector CSS válido como primer argumento. Los elementos del plugin se encuentran con el método querySelector ya que nuestros plugins solo soportan un único elemento.

const modal = new bootstrap.Modal('#myModal')
const dropdown = new bootstrap.Dropdown('[data-bs-toggle="dropdown"]')
const offcanvas = bootstrap.Offcanvas.getInstance('#myOffcanvas')
const alert = bootstrap.Alert.getOrCreateInstance('#myAlert')

Funciones asíncronas y transiciones

Todos los métodos de la API programática son asíncronos y regresan al llamador una vez que la transición ha comenzado, pero antes de que termine. Para ejecutar una acción una vez que la transición se haya completado, puedes escuchar el evento correspondiente.

const myCollapseEl = document.querySelector('#myCollapse')

myCollapseEl.addEventListener('shown.bs.collapse', event => {
  // Action to execute once the collapsible area is expanded
})

Además, una llamada a un método en un componente en transición será ignorada.

const myCarouselEl = document.querySelector('#myCarousel')
const carousel = bootstrap.Carousel.getInstance(myCarouselEl) // Retrieve a Carousel instance

myCarouselEl.addEventListener('slid.bs.carousel', event => {
  carousel.to('2') // Will slide to the slide 2 as soon as the transition to slide 1 is finished
})

carousel.to('1') // Will start sliding to the slide 1 and returns to the caller
carousel.to('2') // !! Will be ignored, as the transition to the slide 1 is not finished !!

`dispose` método

Aunque puede parecer correcto usar el método dispose inmediatamente después de hide(), llevará a resultados incorrectos. Aquí hay un ejemplo del uso problemático:

const myModal = document.querySelector('#myModal')
myModal.hide() // it is asynchronous

myModal.addEventListener('shown.bs.hidden', event => {
  myModal.dispose()
})

Configuración predeterminada

Puedes cambiar la configuración predeterminada de un plugin modificando el objeto Constructor.Default del plugin:

// changes default for the modal plugin's `keyboard` option to false
bootstrap.Modal.Default.keyboard = false

Métodos y propiedades

Cada plugin de Bootstrap expone los siguientes métodos y propiedades estáticas.

Método	Descripción
`dispose`	Destruye el modal de un elemento. (Elimina los datos almacenados en el elemento del DOM)
`getInstance`	Método estático que te permite obtener la instancia del modal asociada a un elemento DOM.
`getOrCreateInstance`	Método estático que te permite obtener la instancia del modal asociada a un elemento DOM, o crear una nueva en caso de que no haya sido inicializada.

Propiedad estática	Descripción
`NAME`	Devuelve el nombre del plugin. (Ejemplo: `bootstrap.Tooltip.NAME`)
`VERSION`	La versión de cada uno de los plugins de Bootstrap puede accederse vía la propiedad `VERSION` del constructor del plugin (Ejemplo: `bootstrap.Tooltip.VERSION`)

Sanitizer

Los Tooltips y Popovers usan nuestro sanitizer integrado para sanitizar las opciones que aceptan HTML.

El valor predeterminado de allowList es el siguiente:

const ARIA_ATTRIBUTE_PATTERN = /^aria-[\w-]*$/i
const DefaultAllowlist = {
  // Global attributes allowed on any supplied element below.
  '*': ['class', 'dir', 'id', 'lang', 'role', ARIA_ATTRIBUTE_PATTERN],
  a: ['target', 'href', 'title', 'rel'],
  area: [],
  b: [],
  br: [],
  col: [],
  code: [],
  div: [],
  em: [],
  hr: [],
  h1: [],
  h2: [],
  h3: [],
  h4: [],
  h5: [],
  h6: [],
  i: [],
  img: ['src', 'srcset', 'alt', 'title', 'width', 'height'],
  li: [],
  ol: [],
  p: [],
  pre: [],
  s: [],
  small: [],
  span: [],
  sub: [],
  sup: [],
  strong: [],
  u: [],
  ul: []
}

Si quieres añadir nuevos valores a este allowList predeterminado puedes hacer lo siguiente:

const myDefaultAllowList = bootstrap.Tooltip.Default.allowList

// To allow table elements
myDefaultAllowList.table = []

// To allow td elements and data-bs-option attributes on td elements
myDefaultAllowList.td = ['data-bs-option']

// You can push your custom regex to validate your attributes.
// Be careful about your regular expressions being too lax
const myCustomRegex = /^data-my-app-[\w-]+/
myDefaultAllowList['*'].push(myCustomRegex)

Si quieres omitir nuestro sanitizer porque prefieres usar una librería dedicada, por ejemplo DOMPurify, deberías hacer lo siguiente:

const yourTooltipEl = document.querySelector('#yourTooltip')
const tooltip = new bootstrap.Tooltip(yourTooltipEl, {
  sanitizeFn(content) {
    return DOMPurify.sanitize(content)
  }
})

Uso opcional de jQuery

No necesitas jQuery en Bootstrap 5, pero sigue siendo posible usar nuestros componentes con jQuery. Si Bootstrap detecta jQuery en el objeto window, añadirá todos nuestros componentes al sistema de plugins de jQuery. Esto te permite hacer lo siguiente:

$('[data-bs-toggle="tooltip"]').tooltip() // to enable tooltips, with default configuration

$('[data-bs-toggle="tooltip"]').tooltip({ boundary: 'clippingParents', customClass: 'myClass' }) // to initialize tooltips with given configuration

$('#myTooltip').tooltip('show') // to trigger `show` method

Lo mismo aplica para nuestros otros componentes.

Sin conflictos

A veces es necesario usar los plugins de Bootstrap con otros frameworks de UI. En estas circunstancias, pueden ocurrir ocasionalmente colisiones de namespace. Si esto ocurre, puedes llamar a .noConflict en el plugin cuyo valor quieras revertir.

const bootstrapButton = $.fn.button.noConflict() // return $.fn.button to previously assigned value
$.fn.bootstrapBtn = bootstrapButton // give $().bootstrapBtn the Bootstrap functionality

Bootstrap no soporta oficialmente bibliotecas de JavaScript de terceros como Prototype o jQuery UI. A pesar de .noConflict y los eventos con namespaces, puede haber problemas de compatibilidad que necesites resolver por tu cuenta.

Eventos de jQuery

Bootstrap detectará jQuery si jQuery está presente en el objeto window y no hay un atributo data-bs-no-jquery establecido en el <body>. Si se encuentra jQuery, Bootstrap emitirá eventos gracias al sistema de eventos de jQuery. Así que si quieres escuchar los eventos de Bootstrap, tendrás que usar los métodos de jQuery (.on, .one) en lugar de addEventListener.

$('#myTab a').on('shown.bs.tab', () => {
  // do something...
})

JavaScript deshabilitado

Los plugins de Bootstrap no tienen un fallback especial cuando JavaScript está deshabilitado. Si te importa la experiencia del usuario en este caso, usa <noscript> para explicar la situación (y cómo reactivar JavaScript) a tus usuarios, y/o añade tus propios fallbacks personalizados.