Ir para o conteúdo principal Pular para a navegação de documentos
Check
in English

Offcanvas

Crie barras laterais ocultas em seu projeto para navegação, carrinhos de compras e muito mais com algumas classes e nosso plug-in JavaScript.

Nesta página

Como funciona

Offcanvas é um componente da barra lateral que pode ser alternado via JavaScript para aparecer na borda esquerda, direita, superior ou inferior da janela de visualização. Botões ou âncoras são usados ​​como gatilhos que são anexados a elementos específicos que você alterna, e dataatributos são usados ​​para invocar nosso JavaScript.

  • Offcanvas compartilha alguns dos mesmos códigos JavaScript como modais. Conceitualmente, eles são bastante semelhantes, mas são plugins separados.
  • Da mesma forma, algumas variáveis ​​Sass de origem para estilos e dimensões do offcanvas são herdadas das variáveis ​​do modal.
  • Quando mostrado, o offcanvas inclui um pano de fundo padrão que pode ser clicado para ocultar o offcanvas.
  • Semelhante aos modais, apenas um offcanvas pode ser mostrado por vez.

Atenção! Dado como o CSS lida com animações, você não pode usar marginou translateem um .offcanvaselemento. Em vez disso, use a classe como um elemento de encapsulamento independente.

O efeito de animação deste componente depende da prefers-reduced-motionconsulta de mídia. Consulte a seção de movimento reduzido de nossa documentação de acessibilidade .

Exemplos

Componentes fora da tela

Abaixo está um exemplo offcanvas que é mostrado por padrão (via .showon .offcanvas). Offcanvas inclui suporte para um cabeçalho com um botão de fechar e uma classe de corpo opcional para alguns arquivos padding. Sugerimos que você inclua cabeçalhos offcanvas com ações de dispensa sempre que possível ou forneça uma ação de dispensa explícita.

Offcanvas
O conteúdo para o offcanvas vai aqui. Você pode colocar praticamente qualquer componente Bootstrap ou elementos personalizados aqui.
html 
<div class="offcanvas offcanvas-start show" tabindex="-1" id="offcanvas" aria-labelledby="offcanvasLabel">
  <div class="offcanvas-header">
    <h5 class="offcanvas-title" id="offcanvasLabel">Offcanvas</h5>
    <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button>
  </div>
  <div class="offcanvas-body">
    Content for the offcanvas goes here. You can place just about any Bootstrap component or custom elements here.
  </div>
</div>

Demonstração ao vivo

Use os botões abaixo para mostrar e ocultar um elemento offcanvas via JavaScript que alterna a .showclasse em um elemento com a .offcanvasclasse.

  • .offcanvasoculta o conteúdo (padrão)
  • .offcanvas.showmostra o conteúdo

Você pode usar um link com o hrefatributo ou um botão com o data-bs-targetatributo. Em ambos os casos, o data-bs-toggle="offcanvas"é necessário.

Link com href
Offcanvas
Algum texto como espaço reservado. Na vida real você pode ter os elementos que escolheu. Como, texto, imagens, listas, etc.
html 
<a class="btn btn-primary" data-bs-toggle="offcanvas" href="#offcanvasExample" role="button" aria-controls="offcanvasExample">
  Link with href
</a>
<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasExample" aria-controls="offcanvasExample">
  Button with data-bs-target
</button>

<div class="offcanvas offcanvas-start" tabindex="-1" id="offcanvasExample" aria-labelledby="offcanvasExampleLabel">
  <div class="offcanvas-header">
    <h5 class="offcanvas-title" id="offcanvasExampleLabel">Offcanvas</h5>
    <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button>
  </div>
  <div class="offcanvas-body">
    <div>
      Some text as placeholder. In real life you can have the elements you have chosen. Like, text, images, lists, etc.
    </div>
    <div class="dropdown mt-3">
      <button class="btn btn-secondary dropdown-toggle" type="button" data-bs-toggle="dropdown">
        Dropdown button
      </button>
      <ul class="dropdown-menu">
        <li><a class="dropdown-item" href="#">Action</a></li>
        <li><a class="dropdown-item" href="#">Another action</a></li>
        <li><a class="dropdown-item" href="#">Something else here</a></li>
      </ul>
    </div>
  </div>
</div>

Rolagem do corpo

A rolagem do <body>elemento é desabilitada quando um offcanvas e seu pano de fundo estão visíveis. Use o data-bs-scrollatributo para habilitar a <body>rolagem.

Offcanvas com rolagem do corpo

Tente rolar o resto da página para ver essa opção em ação.

html 
<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasScrolling" aria-controls="offcanvasScrolling">Enable body scrolling</button>

<div class="offcanvas offcanvas-start" data-bs-scroll="true" data-bs-backdrop="false" tabindex="-1" id="offcanvasScrolling" aria-labelledby="offcanvasScrollingLabel">
  <div class="offcanvas-header">
    <h5 class="offcanvas-title" id="offcanvasScrollingLabel">Offcanvas with body scrolling</h5>
    <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button>
  </div>
  <div class="offcanvas-body">
    <p>Try scrolling the rest of the page to see this option in action.</p>
  </div>
</div>

Rolagem do corpo e pano de fundo

Você também pode ativar <body>a rolagem com um pano de fundo visível.

Pano de fundo com rolagem

Tente rolar o resto da página para ver essa opção em ação.

html 
<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasWithBothOptions" aria-controls="offcanvasWithBothOptions">Enable both scrolling & backdrop</button>

<div class="offcanvas offcanvas-start" data-bs-scroll="true" tabindex="-1" id="offcanvasWithBothOptions" aria-labelledby="offcanvasWithBothOptionsLabel">
  <div class="offcanvas-header">
    <h5 class="offcanvas-title" id="offcanvasWithBothOptionsLabel">Backdrop with scrolling</h5>
    <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button>
  </div>
  <div class="offcanvas-body">
    <p>Try scrolling the rest of the page to see this option in action.</p>
  </div>
</div>

Pano de fundo estático

Quando o pano de fundo é definido como estático, o offcanvas não será fechado ao clicar fora dele.

Offcanvas
Não vou fechar se você clicar fora de mim.
html 
<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#staticBackdrop" aria-controls="staticBackdrop">
  Toggle static offcanvas
</button>

<div class="offcanvas offcanvas-start" data-bs-backdrop="static" tabindex="-1" id="staticBackdrop" aria-labelledby="staticBackdropLabel">
  <div class="offcanvas-header">
    <h5 class="offcanvas-title" id="staticBackdropLabel">Offcanvas</h5>
    <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button>
  </div>
  <div class="offcanvas-body">
    <div>
      I will not close if you click outside of me.
    </div>
  </div>
</div>

Offscreen escuro

Adicionado na v5.2.0

Altere a aparência de offcanvases com utilitários para melhor combiná-los com diferentes contextos, como barras de navegação escuras. Aqui nós adicionamos .text-bg-darkao .offcanvase .btn-close-whitepara .btn-closeum estilo adequado com uma offcanvas escura. Se você tiver menus suspensos, considere também adicionar .dropdown-menu-darka .dropdown-menu.

Offcanvas

Coloque o conteúdo offcanvas aqui.

html 
<div class="offcanvas offcanvas-start show text-bg-dark" tabindex="-1" id="offcanvasDark" aria-labelledby="offcanvasDarkLabel">
  <div class="offcanvas-header">
    <h5 class="offcanvas-title" id="offcanvasDarkLabel">Offcanvas</h5>
    <button type="button" class="btn-close btn-close-white" data-bs-dismiss="offcanvasDark" aria-label="Close"></button>
  </div>
  <div class="offcanvas-body">
    <p>Place offcanvas content here.</p>
  </div>
</div>

Responsivo

Adicionado na v5.2.0

As classes offcanvas responsivas ocultam o conteúdo fora da janela de visualização de um ponto de interrupção especificado e para baixo. Acima desse ponto de interrupção, o conteúdo interno se comportará como de costume. Por exemplo, .offcanvas-lgoculta o conteúdo em uma offcanvas abaixo do lgponto de interrupção, mas mostra o conteúdo acima do ponto de lginterrupção.

Redimensione seu navegador para mostrar a alternância offcanvas responsiva.
Offcanvas responsivo

Este é o conteúdo dentro de um arquivo .offcanvas-lg.

html 
<button class="btn btn-primary d-lg-none" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasResponsive" aria-controls="offcanvasResponsive">Toggle offcanvas</button>

<div class="alert alert-info d-none d-lg-block">Resize your browser to show the responsive offcanvas toggle.</div>

<div class="offcanvas-lg offcanvas-end" tabindex="-1" id="offcanvasResponsive" aria-labelledby="offcanvasResponsiveLabel">
  <div class="offcanvas-header">
    <h5 class="offcanvas-title" id="offcanvasResponsiveLabel">Responsive offcanvas</h5>
    <button type="button" class="btn-close" data-bs-dismiss="offcanvas" data-bs-target="#offcanvasResponsive" aria-label="Close"></button>
  </div>
  <div class="offcanvas-body">
    <p class="mb-0">This is content within an <code>.offcanvas-lg</code>.</p>
  </div>
</div>

As classes offcanvas responsivas estão disponíveis para cada ponto de interrupção.

  • .offcanvas
  • .offcanvas-sm
  • .offcanvas-md
  • .offcanvas-lg
  • .offcanvas-xl
  • .offcanvas-xxl

Canal

Não há posicionamento padrão para componentes offcanvas, portanto, você deve adicionar uma das classes modificadoras abaixo.

  • .offcanvas-startcoloca offcanvas à esquerda da janela de visualização (mostrado acima)
  • .offcanvas-endcoloca offcanvas à direita da janela de visualização
  • .offcanvas-topcoloca offcanvas no topo da janela de visualização
  • .offcanvas-bottomcoloca offcanvas na parte inferior da viewport

Experimente os exemplos superior, direito e inferior abaixo.

Parte superior off-canvas
...
html 
<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasTop" aria-controls="offcanvasTop">Toggle top offcanvas</button>

<div class="offcanvas offcanvas-top" tabindex="-1" id="offcanvasTop" aria-labelledby="offcanvasTopLabel">
  <div class="offcanvas-header">
    <h5 class="offcanvas-title" id="offcanvasTopLabel">Offcanvas top</h5>
    <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button>
  </div>
  <div class="offcanvas-body">
    ...
  </div>
</div>
Fora da tela à direita
...
html 
<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasRight" aria-controls="offcanvasRight">Toggle right offcanvas</button>

<div class="offcanvas offcanvas-end" tabindex="-1" id="offcanvasRight" aria-labelledby="offcanvasRightLabel">
  <div class="offcanvas-header">
    <h5 class="offcanvas-title" id="offcanvasRightLabel">Offcanvas right</h5>
    <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button>
  </div>
  <div class="offcanvas-body">
    ...
  </div>
</div>
Parte inferior da tela
...
html 
<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasBottom" aria-controls="offcanvasBottom">Toggle bottom offcanvas</button>

<div class="offcanvas offcanvas-bottom" tabindex="-1" id="offcanvasBottom" aria-labelledby="offcanvasBottomLabel">
  <div class="offcanvas-header">
    <h5 class="offcanvas-title" id="offcanvasBottomLabel">Offcanvas bottom</h5>
    <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button>
  </div>
  <div class="offcanvas-body small">
    ...
  </div>
</div>

Acessibilidade

Como o painel offcanvas é conceitualmente uma caixa de diálogo modal, certifique-se de adicionar aria-labelledby="..."—referenciando o título offcanvas—ao arquivo .offcanvas. Observe que você não precisa adicionar role="dialog", pois já o adicionamos via JavaScript.

CSS

Variáveis

Adicionado na v5.2.0

Como parte da abordagem de variáveis ​​CSS em evolução do Bootstrap, o offcanvas agora usa variáveis ​​CSS locais .offcanvaspara personalização aprimorada em tempo real. Os valores das variáveis ​​CSS são definidos por meio do Sass, portanto, a personalização do Sass também é suportada.

  --#{$prefix}offcanvas-zindex: #{$zindex-offcanvas};
  --#{$prefix}offcanvas-width: #{$offcanvas-horizontal-width};
  --#{$prefix}offcanvas-height: #{$offcanvas-vertical-height};
  --#{$prefix}offcanvas-padding-x: #{$offcanvas-padding-x};
  --#{$prefix}offcanvas-padding-y: #{$offcanvas-padding-y};
  --#{$prefix}offcanvas-color: #{$offcanvas-color};
  --#{$prefix}offcanvas-bg: #{$offcanvas-bg-color};
  --#{$prefix}offcanvas-border-width: #{$offcanvas-border-width};
  --#{$prefix}offcanvas-border-color: #{$offcanvas-border-color};
  --#{$prefix}offcanvas-box-shadow: #{$offcanvas-box-shadow};

Variáveis ​​atrevidas

$offcanvas-padding-y:               $modal-inner-padding;
$offcanvas-padding-x:               $modal-inner-padding;
$offcanvas-horizontal-width:        400px;
$offcanvas-vertical-height:         30vh;
$offcanvas-transition-duration:     .3s;
$offcanvas-border-color:            $modal-content-border-color;
$offcanvas-border-width:            $modal-content-border-width;
$offcanvas-title-line-height:       $modal-title-line-height;
$offcanvas-bg-color:                $modal-content-bg;
$offcanvas-color:                   $modal-content-color;
$offcanvas-box-shadow:              $modal-content-box-shadow-xs;
$offcanvas-backdrop-bg:             $modal-backdrop-bg;
$offcanvas-backdrop-opacity:        $modal-backdrop-opacity;

Uso

O plugin offcanvas utiliza algumas classes e atributos para lidar com o trabalho pesado:

  • .offcanvasesconde o conteúdo
  • .offcanvas.showmostra o conteúdo
  • .offcanvas-startesconde o offcanvas à esquerda
  • .offcanvas-endesconde o offcanvas à direita
  • .offcanvas-topesconde o offcanvas na parte superior
  • .offcanvas-bottomesconde o offcanvas na parte inferior

Adicione um botão de dispensa com o data-bs-dismiss="offcanvas"atributo, que aciona a funcionalidade JavaScript. Certifique-se de usar o <button>elemento com ele para um comportamento adequado em todos os dispositivos.

Por atributos de dados

Alternar

Adicione data-bs-toggle="offcanvas"e um data-bs-targetou hrefao elemento para atribuir automaticamente o controle de um elemento offcanvas. O data-bs-targetatributo aceita um seletor CSS ao qual aplicar o offcanvas. Certifique-se de adicionar a classe offcanvasao elemento offcanvas. Se você quiser que ele seja aberto por padrão, adicione a classe adicional show.

Dispensar

A demissão pode ser obtida com o dataatributo em um botão dentro do offcanvas , conforme demonstrado abaixo:

<button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button>

ou em um botão fora do offcanvas usando o data-bs-targetconforme demonstrado abaixo:

<button type="button" class="btn-close" data-bs-dismiss="offcanvas" data-bs-target="#my-offcanvas" aria-label="Close"></button>
Embora ambas as formas de dispensar um offcanvas sejam suportadas, lembre-se de que dispensar de fora um offcanvas não corresponde ao padrão de diálogo (modal) do ARIA Authoring Practices Guide . Faça isso por sua conta e risco.

Por JavaScript

Ative manualmente com:

const offcanvasElementList = document.querySelectorAll('.offcanvas')
const offcanvasList = [...offcanvasElementList].map(offcanvasEl => new bootstrap.Offcanvas(offcanvasEl))

Opções

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="{value}". Certifique-se de alterar o tipo de caso 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 experimental de dados reservados data-bs-configque pode abrigar a configuração simples do componente como uma string JSON. Quando um elemento tem atributos data-bs-config='{"delay":0, "title":123}'e data-bs-title="456", o valor final titleserá 456e os atributos de dados separados substituirão os valores fornecidos em data-bs-config. Além disso, os atributos de dados existentes podem hospedar valores JSON como data-bs-delay='{"show":0,"hide":150}'.

Nome Modelo Predefinição Descrição
backdrop booleano ou a stringstatic true Aplique um pano de fundo no corpo enquanto o offcanvas estiver aberto. Alternativamente, especifique staticpara um pano de fundo que não feche o offcanvas quando clicado.
keyboard boleano true Fecha o offcanvas quando a tecla Escape é pressionada.
scroll boleano false Permitir a rolagem do corpo enquanto o offcanvas estiver aberto.

Métodos

Métodos e transições assíncronas

Todos os métodos de API são assíncronos e iniciam uma transição . Eles retornam ao chamador assim que a transição é iniciada, mas antes que ela termine . Além disso, uma chamada de método em um componente de transição será ignorada .

Consulte nossa documentação JavaScript para obter mais informações .

Ativa seu conteúdo como um elemento offcanvas. Aceita opções opcionais object.

Você pode criar uma instância offcanvas com o construtor, por exemplo:

const bsOffcanvas = new bootstrap.Offcanvas('#myOffcanvas')
Método Descrição
getInstance Método estático que permite obter a instância offcanvas associada a um elemento DOM.
getOrCreateInstance Método estático que permite obter a instância offcanvas associada a um elemento DOM ou criar uma nova caso não tenha sido inicializada.
hide Oculta um elemento offcanvas. Retorna ao chamador antes que o elemento offcanvas tenha sido ocultado (ou seja, antes que o hidden.bs.offcanvasevento ocorra).
show Mostra um elemento offcanvas. Retorna ao chamador antes que o elemento offcanvas tenha sido realmente mostrado (ou seja, antes que o shown.bs.offcanvasevento ocorra).
toggle Alterna um elemento offcanvas para mostrado ou oculto. Retorna ao chamador antes que o elemento offcanvas tenha realmente sido mostrado ou ocultado (ou seja, antes que o evento shown.bs.offcanvasou hidden.bs.offcanvasocorra).

Eventos

A classe offcanvas do Bootstrap expõe alguns eventos para conexão com a funcionalidade offcanvas.

Tipo de evento Descrição
hide.bs.offcanvas Este evento é disparado imediatamente quando o hidemétodo é chamado.
hidden.bs.offcanvas Este evento é acionado quando um elemento offcanvas foi ocultado do usuário (aguardará a conclusão das transições CSS).
hidePrevented.bs.offcanvas Este evento é acionado quando o offcanvas é exibido, seu pano de fundo é exibido statice um clique fora do offcanvas é executado. O evento também é acionado quando a tecla Escape é pressionada e a keyboardopção é definida como false.
show.bs.offcanvas Este evento é acionado imediatamente quando o showmétodo de instância é chamado.
shown.bs.offcanvas Este evento é acionado quando um elemento offcanvas se torna visível para o usuário (aguardará a conclusão das transições CSS). 
const myOffcanvas = document.getElementById('myOffcanvas')
myOffcanvas.addEventListener('hidden.bs.offcanvas', event => {
  // do something...
})