JavaScript#

Dê vida ao Bootstrap com nossos plug-ins JavaScript opcionais. Aprenda sobre cada plug-in, nossas opções de API programática e de dados e muito mais.

Individual ou compilado#

Plugins podem ser incluídos individualmente (usando os arquivos individuais js/dist/*.js do Bootstrap), ou todos de uma vez usando bootstrap.js ou o bootstrap.min.js minificado (não inclua ambos).

Se você usar um empacotador (Webpack, Parcel, Vite...), você pode usar arquivos /js/dist/*.js que são prontos para UMD.

Uso com frameworks JavaScript#

Embora o CSS Bootstrap possa ser usado com qualquer framework, o JavaScript Bootstrap não é totalmente compatível com frameworks JavaScript como React, Vue e Angular, que assumem conhecimento total do DOM. Tanto o Bootstrap quanto o framework podem tentar modificar o mesmo elemento DOM, resultando em falhas como menus suspensos que ficam presos na posição "aberto".

Uma alternativa melhor para aqueles que usam esse tipo de framework é usar um pacote específico do framework em vez do JavaScript Bootstrap. Aqui estão algumas das opções mais populares:

Usando Bootstrap como um módulo#

Faça um teste! Baixe o código-fonte e a demonstração funcional de uso do Bootstrap como um módulo ES do repositório twbs/examples. Você também pode abrir o exemplo no StackBlitz.

Nós fornecemos uma versão do Bootstrap construída como ESM (bootstrap.esm.js e bootstrap.esm.min.js) que permite que você use o Bootstrap como um módulo no navegador, se os navegadores alvos o suportarem.

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

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

Comparado aos empacotadores JS, usar ESM no navegador requer que você use o caminho completo e o nome do arquivo em vez do nome do módulo. Leia mais sobre módulos JS no navegador. É por isso que usamos 'bootstrap.esm.min.js' em vez de 'bootstrap' acima. No entanto, isso é ainda mais complicado por nossa dependência Popper, que importa Popper para nosso JavaScript assim:

import * as Popper from "@popperjs/core"

Se você tentar fazer isso do jeito que está, verá um erro no console como o seguinte:

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

Para corrigir isso, você pode usar um importmap para resolver os nomes de módulos arbitrários para caminhos completos. Se seus navegadores alvos não suportam importmap, você precisará usar o projeto es-module-shims. Veja como funciona para Bootstrap e Popper:

<!doctype html>
<html lang="pt-br">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <link href="https://cdn.jsdelivr.net/npm/[email protected]/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-QWTKZyjpPEjISv5WaRU9OFeRpok6YctnYmDr5pNlyT2bRjXh0JMhjY6hW+ALEwIH"
        crossorigin="anonymous">
  <title>Olá, modularidade!</title>
</head>
<body>
<h1>Olá, modularidade!</h1>
<button id="popoverButton" type="button" class="btn btn-primary btn-lg"
        data-bs-toggle="popover" title="ESM no navegador"
        data-bs-content="Bang!">
  Popover personalizado
</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/[email protected]/dist/esm/popper.min.js",
      "bootstrap": "https://cdn.jsdelivr.net/npm/[email protected]/dist/js/bootstrap.esm.min.js"
    }
  }
</script>
<script type="module">
  import * as bootstrap from 'bootstrap'

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

Dependências#

Alguns plug-ins e componentes CSS dependem de outros plug-ins. Se você incluir plug-ins individualmente, certifique-se de verificar essas dependências na documentação.

Nossos menus suspensos, popovers e tooltips também dependem do Popper.

Atributos de dados#

Quase todos os plug-ins Bootstrap podem ser habilitados e configurados apenas com HTML com atributos de dados (nossa maneira preferida de usar a funcionalidade JavaScript). Certifique-se de usar apenas um conjunto de atributos de dados em um único elemento (por exemplo, você não pode acionar uma tooltip e um modal do mesmo botão).

Como as opções podem ser passadas por meio de atributos de dados ou JavaScript, você pode anexar um nome de opção a data-bs-, como em data-bs-animation="{valor}". Certifique-se de alterar o formato do nome da opção de "camelCase" para "kebab-case" ao passar as opções por meio de atributos de dados. Por exemplo, use data-bs-custom-class="beautifier" em vez de data-bs-customClass="beautifier".

A partir do Bootstrap 5.2.0, todos os componentes oferecem suporte a um atributo de dados reservado experimental data-bs-config que pode abrigar uma configuração de componente simples como uma string JSON. Quando um elemento tem os atributos data-bs-config='{"delay":0, "title":123}' e data-bs-title="456", o valor final de title será 456 e os atributos de dados separados substituirão os valores fornecidos em data-bs-config. Além disso, os atributos de dados existentes são capazes de abrigar valores JSON como data-bs-delay='{"show":0,"hide":150}'.

O objeto de configuração final é o resultado da união de data-bs-config, data-bs- e js object, onde o último valor-chave fornecido substitui os outros.

Seletores#

Usamos os métodos nativos querySelector e querySelectorAll para consultar elementos DOM por motivos de desempenho, então você deve usar seletores válidos. Se você usar seletores especiais como collapse:Exemplo, certifique-se de escapá-los.

Eventos#

O Bootstrap fornece eventos personalizados para a maioria das ações exclusivas dos plug-ins. Geralmente, eles vêm em uma forma infinitiva e particípio passado - onde o infinitivo (ex. show) é acionado no início de um evento, e sua forma particípio passado (ex. shown) é acionada na conclusão de uma ação.

Todos os eventos infinitivos fornecem a funcionalidade preventDefault(). Isso fornece a capacidade de interromper a execução de uma ação antes que ela comece. Retornar false de um manipulador de eventos também chamará preventDefault() automaticamente.

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

myModal.addEventListener('show.bs.modal', event => {
    return event.preventDefault() // impede que o modal seja exibido
})

API programática#

Todos os construtores aceitam um objeto opcional de opções ou nada (o que inicia um plug-in com seu comportamento padrão):

const myModalEl = document.querySelector('#myModal')
const modal = new bootstrap.Modal(myModalEl) // inicializado com padrões

const configObject = { keyboard: false }
const modal1 = new bootstrap.Modal(myModalEl, configObject) // inicializado sem teclado

Se você quiser obter uma instância de plug-in específica, cada plug-in expõe um método getInstance. Por exemplo, para recuperar uma instância diretamente de um elemento:

bootstrap.Popover.getInstance(myPopoverEl)

Este método retornará null se uma instância não for inicializada através do elemento solicitado.

Alternativamente, getOrCreateInstance pode ser usado para obter a instância associada a um elemento DOM, ou criar uma nova caso ela não tenha sido inicializada.

bootstrap.Popover.getOrCreateInstance(myPopoverEl, configObject)

Caso uma instância não tenha sido inicializada, ela pode aceitar e usar um objeto de configuração opcional como segundo argumento.

Seletores CSS em construtores#

Além dos métodos getInstance e getOrCreateInstance, todos os construtores de plug-in podem aceitar um elemento DOM ou um seletor CSS válido como o primeiro argumento. Elementos de plug-in são encontrados com o método querySelector, já que nossos plug-ins suportam apenas um ú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')

Funções e transições assíncronas#

Todos os métodos de API programática são assíncronos e retornam ao chamador assim que a transição é iniciada, mas antes de terminar. Para executar uma ação assim que a transição for concluída, você pode ouvir o evento correspondente.

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

myCollapseEl.addEventListener('shown.bs.collapse', event => {
  // Ação a ser executada quando a área recolhível for expandida
})

Além disso, uma chamada de método em um componente em transição será ignorada.

const myCarouselEl = document.querySelector('#myCarousel')
const carousel = bootstrap.Carousel.getInstance(myCarouselEl) // Recupera uma instância de Carousel

myCarouselEl.addEventListener('slid.bs.carousel', event => {
  carousel.to('2') // Deslizará para o slide 2 assim que a transição para o slide 1 for concluída
})

carousel.to('1') // Começará a deslizar para o slide 1 e retornará para o chamador
carousel.to('2') // !! Será ignorado, pois a transição para o slide 1 não foi concluída !!

Método dispose#

Embora possa parecer correto usar o método dispose imediatamente após hide(), isso levará a resultados incorretos. Aqui está um exemplo de uso problemático:

const myModal = document.querySelector('#myModal')
myModal.hide() // é assíncrono

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

Configurações padrão#

Você pode alterar as configurações padrão de um plug-in modificando o objeto Constructor.Default do plug-in:

// altera o padrão para a opção `keyboard` do plug-in modal para false
bootstrap.Modal.Default.keyboard = false

Métodos e propriedades#

Cada plug-in Bootstrap expõe os seguintes métodos e propriedades estáticas.

Método Descrição
dispose Destrói o modal de um elemento. (Remove os dados armazenados no elemento DOM).
getInstance Método estático que permite obter a instância modal associada a um elemento DOM.
getOrCreateInstance Método estático que permite obter a instância modal associada a um elemento DOM ou criar uma nova caso ela não tenha sido inicializada.
Propriedade estática Descrição
NAME Retorna o nome do plug-in. (Exemplo: bootstrap.Tooltip.NAME)
VERSION A versão de cada um dos plug-ins do Bootstrap pode ser acessada através da propriedade VERSION do construtor do plug-in (Exemplo: bootstrap.Tooltip.VERSION)

Sanitizador#

Tooltips e Popovers usam nosso sanitizador integrado para sanitizar opções que aceitam HTML.

O valor padrão de allowList é o seguinte:

// https://github.com/twbs/bootstrap/blob/v5.3.3/js/src/util/sanitizer.js

const ARIA_ATTRIBUTE_PATTERN = /^aria-[\w-]*$/i

export const DefaultAllowlist = {
  // Atributos globais permitidos em qualquer elemento fornecido abaixo.
  '*': ['class', 'dir', 'id', 'lang', 'role', ARIA_ATTRIBUTE_PATTERN],
  a: ['target', 'href', 'title', 'rel'],
  area: [],
  b: [],
  br: [],
  col: [],
  code: [],
  dd: [],
  div: [],
  dl: [],
  dt: [],
  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: []
}

Se você quiser adicionar novos valores a esta allowList padrão, você pode fazer o seguinte:

const myDefaultAllowList = bootstrap.Tooltip.Default.allowList

// Para permitir elementos de tabela
myDefaultAllowList.table = []

// Para permitir elementos td e atributos data-bs-option em elementos td
myDefaultAllowList.td = ['data-bs-option']

// Você pode enviar sua expressão regular personalizada para validar seus
// atributos.
// Tenha cuidado com suas expressões regulares sendo muito frouxas.
const myCustomRegex = /^data-my-app-[\w-]+/
myDefaultAllowList['*'].push(myCustomRegex)

Se você quiser ignorar nosso sanitizador porque prefere usar uma biblioteca dedicada, por exemplo, DOMPurify, você deve fazer o seguinte:

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

Usando jQuery opcionalmente#

Você não precisa do jQuery no Bootstrap 5, mas ainda é possível usar nossos componentes com o jQuery. Se o Bootstrap detectar jQuery no objeto window, ele adicionará todos os nossos componentes no sistema de plug-ins do jQuery. Isso permite que você faça o seguinte:

// para habilitar tooltips com a configuração padrão
$('[data-bs-toggle="tooltip"]').tooltip()

// para inicializar tooltips com a configuração fornecida
$('[data-bs-toggle="tooltip"]').tooltip({
  boundary: 'clippingParents',
  customClass: 'myClass'
})

// para acionar o método `show`
$('#myTooltip').tooltip('show')

O mesmo vale para nossos outros componentes.

Sem conflitos#

Às vezes é necessário usar plug-ins Bootstrap com outras estruturas de UI. Nessas circunstâncias, colisões de namespace podem ocorrer ocasionalmente. Se isso acontecer, você pode chamar .noConflict no plug-in cujo valor deseja reverter.

const bootstrapButton = $.fn.button.noConflict() // retorna $.fn.button ao valor atribuído anteriormente
$.fn.bootstrapBtn = bootstrapButton // dá a $().bootstrapBtn a funcionalidade Bootstrap

O Bootstrap não suporta oficialmente bibliotecas JavaScript de terceiros como Prototype ou jQuery UI. Apesar do .noConflict e dos eventos com namespaces, pode haver problemas de compatibilidade que você precisa corrigir por conta própria.

Eventos jQuery#

O Bootstrap detectará o jQuery se jQuery estiver presente no objeto window e não houver atributo data-bs-no-jquery definido em <body>. Se o jQuery for encontrado, o Bootstrap emitirá eventos graças ao sistema de eventos do jQuery. Então, se você quiser ouvir os eventos do Bootstrap, terá que usar os métodos jQuery (.on, .one) em vez de addEventListener.

$('#myTab a').on('shown.bs.tab', () => {
  // faça alguma coisa...
})

JavaScript desabilitado#

Os plug-ins do Bootstrap não têm uma última alternativa especial quando o JavaScript está desabilitado. Se você se importa com a experiência da pessoa usuária neste caso, use <noscript> para explicar a situação (e como reabilitar o JavaScript) para suas pessoas usuárias e/ou adicione suas últimas alternativas personalizadas.