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.

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

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.

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.

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.

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.

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.

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.

...

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>

...

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>

...

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 string`static`	`true`	Aplique um pano de fundo no corpo enquanto o offcanvas estiver aberto. Alternativamente, especifique `static`para 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.offcanvas`evento 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.offcanvas`evento 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.offcanvas`ou `hidden.bs.offcanvas`ocorra).

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 `hide`mé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 `static`e um clique fora do offcanvas é executado. O evento também é acionado quando a tecla Escape é pressionada e a `keyboard`opção é definida como `false`.
`show.bs.offcanvas`	Este evento é acionado imediatamente quando o `show`mé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...
})

Offcanvas

Como funciona

Exemplos

Componentes fora da tela

Offcanvas

Demonstração ao vivo

Offcanvas

Rolagem do corpo

Offcanvas com rolagem do corpo

Rolagem do corpo e pano de fundo

Pano de fundo com rolagem

Pano de fundo estático

Offcanvas

Offscreen escuro

Offcanvas

Responsivo

Offcanvas responsivo

Canal

Parte superior off-canvas

Fora da tela à direita

Parte inferior da tela

Acessibilidade

CSS

Variáveis

Variáveis atrevidas

Uso

Por atributos de dados

Alternar

Dispensar

Por JavaScript

Opções

Métodos

Métodos e transições assíncronas

Eventos

Offcanvas

Como funciona

Exemplos

Componentes fora da tela

Offcanvas

Demonstração ao vivo

Offcanvas

Rolagem do corpo

Offcanvas com rolagem do corpo

Rolagem do corpo e pano de fundo

Pano de fundo com rolagem

Pano de fundo estático

Offcanvas

Offscreen escuro

Offcanvas

Responsivo

Offcanvas responsivo

Canal

Parte superior off-canvas

Fora da tela à direita

Parte inferior da tela

Acessibilidade

CSS

Variáveis

Variáveis ​​atrevidas

Uso

Por atributos de dados

Alternar

Dispensar

Por JavaScript

Opções

Métodos

Métodos e transições assíncronas

Eventos

Variáveis atrevidas