내용으로 건너뛰기 문서 내비게이션으로 건너뛰기
GitHub에서 보기

오프캔버스

// Offcanvas

몇 가지의 클래스와 JavaScript 플러그인을 사용해 네비게이션이나 쇼핑카트 등에 유용한 숨겨진 사이드바를 사용할 수 있습니다.

목차
이 페이지는 전체 또는 일부분이 아직 한국어로 번역되지 않았어요. 😢 GitHub에서 한국어로 번역할 수 있도록 도와주세요

작동 원리

Offcanvas is a sidebar component that can be toggled via JavaScript to appear from the left, right, top, or bottom edge of the viewport. Buttons or anchors are used as triggers that are attached to specific elements you toggle, and data attributes are used to invoke our JavaScript.

  • 오프캔버스는 모달과 같이 JavaScript 코드를 일부 공유하고 있습니다. 개념적으로는 아주 비슷하지만 이들은 다른 플러그인입니다.
  • 마찬가지로, 오프캔버승의 스타일과 치수를 위한 Sass 소스 변수의 일부는 모달 변수로부터 상속받고 있습니다.
  • 오프캔버스를 표시하면 기본적으로 배경이 포함되어져 있어 그것을 클릭하면 오프캔버스가 사라집니다.
  • 모달과 마찬가지로 오프캔버스는 한번에 1개밖에 표시할 수 없습니다.

주의! CSS에 의한 애니메이션 사용을 고려한다면 .offcanvas 요소의 margin이나 translate를 사용할 수 없습니다. 대신, 이 클래스를 독립된 포장 요소 감싸서 사용해 주세요.

이 컴포넌트의 애니메이션 효과는 prefers-reduced-motion 미디어 쿼리에 따라 다릅니다. 접근성 문서의 모션 감소 문단을 참고하세요.

예시

오프캔버스 컴포넌트

다음은 기본적으로 표시되는(.offcanvas의 .show에 의해) 오프캔버스의 예시입니다. 오프캔버스에는 닫기 버튼이 있는 헤더와 초기 padding을 위한 옵션의 body클래스가 지원됩니다. 가능한 오프캔버스의 헤더에 닫기 액션을 포함시키거나 명시적인 닫기 액션을 제공할 것을 권장합니다.

Offcanvas
Content for the offcanvas goes here. You can place just about any Bootstrap component or custom elements here.
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>

라이브 데모

아래의 버튼을 클릭하면 .offcanvas 클래스를 갖고 있는 요소의 .show 클래스를 토글하는 JavaScript로 오프캔버스를 표시/숨김하는 것을 확인할 수 있습니다.

  • .offcanvas 콘텐츠를 숨김 (기본)
  • .offcanvas.show 콘텐츠를 표시

href 속성으로 링크를, data-bs-target 속성으로 버튼을 사용할 수 있습니다. 어느 경우든 data-bs-toggle="offcanvas"가 필요합니다.

Link with href
Offcanvas
Some text as placeholder. In real life you can have the elements you have chosen. Like, text, images, lists, 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>

Body scrolling

Scrolling the <body> element is disabled when an offcanvas and its backdrop are visible. Use the data-bs-scroll attribute to enable <body> scrolling.

Offcanvas with body scrolling

Try scrolling the rest of the page to see this option in action.

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>

Body scrolling and backdrop

You can also enable <body> scrolling with a visible backdrop.

Backdrop with scrolling

Try scrolling the rest of the page to see this option in action.

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>

Static backdrop

When backdrop is set to static, the offcanvas will not close when clicking outside of it.

Offcanvas
I will not close if you click outside of me.
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>

Dark offcanvas

Deprecated in v5.3.0 v5.2.0에서 추가됨

Change the appearance of offcanvases with utilities to better match them to different contexts like dark navbars. Here we add .text-bg-dark to the .offcanvas and .btn-close-white to .btn-close for proper styling with a dark offcanvas. If you have dropdowns within, consider also adding .dropdown-menu-dark to .dropdown-menu.

Heads up! Dark variants for components were deprecated in v5.3.0 with the introduction of color modes. Instead of manually adding classes mentioned above, set data-bs-theme="dark" on the root element, a parent wrapper, or the component itself.
Offcanvas

Place offcanvas content here.

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>

Responsive

v5.2.0에서 추가됨

Responsive offcanvas classes hide content outside the viewport from a specified breakpoint and down. Above that breakpoint, the contents within will behave as usual. For example, .offcanvas-lg hides content in an offcanvas below the lg breakpoint, but shows the content above the lg breakpoint.

Resize your browser to show the responsive offcanvas toggle.
Responsive offcanvas

This is content within an .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>

Responsive offcanvas classes are available across for each breakpoint.

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

배치

오프캔버스 컴포넌트의 기본 배치는 없으므로 아래 제어자 클래스 중 하나를 추가해야 합니다:

  • .offcanvas-start는 오프캔버스를 뷰포트의 왼쪽에 배치합니다 (위의 예시로 확인)
  • .offcanvas-end는 오프캔버스를 뷰포트의 오른쪽에 배치합니다.
  • .offcanvas-top은 뷰포트의 맨 위에 오프캔버스를 배치합니다.
  • .offcanvas-bottom은 뷰포트의 맨 아래에 오프캔버스를 배치합니다.

위, 오른쪽, 아래에서 나오는 오프캔버스를 아래의 예시에서 확인해 보세요.

Offcanvas top
...
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>
Offcanvas right
...
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>
Offcanvas bottom
...
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>

접근성

개념적으로 오프캔버스 패널은 모달 dialog여서, 반드시 .offcanvas에 aria-labelledby="..."라는 오프캔버스의 타이틀을 참조하는 기술을 추가해 주세요. 덧붙여 role="dialog"는 이미 JavaScript로 추가되고 있기 때문에 따로 추가할 필요는 없습니다.

CSS

변수

v5.2.0에서 추가됨

As part of Bootstrap’s evolving CSS variables approach, offcanvas now uses local CSS variables on .offcanvas for enhanced real-time customization. Values for the CSS variables are set via Sass, so Sass customization is still supported, too.

scss/_offcanvas.scss 
--#{$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};
--#{$prefix}offcanvas-transition: #{transform $offcanvas-transition-duration ease-in-out};
--#{$prefix}offcanvas-title-line-height: #{$offcanvas-title-line-height};

Sass 변수

scss/_variables.scss 
$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:                var(--#{$prefix}body-bg);
$offcanvas-color:                   var(--#{$prefix}body-color);
$offcanvas-box-shadow:              $modal-content-box-shadow-xs;
$offcanvas-backdrop-bg:             $modal-backdrop-bg;
$offcanvas-backdrop-opacity:        $modal-backdrop-opacity;

사용 방법

오프캔버스 플러그인에서는 몇 가지 클래스와 속성을 이용하여 힘든 처리를 합니다:

  • .offcanvas는 콘텐츠를 숨깁니다.
  • .offcanvas.show는 콘텐츠를 표시합니다.
  • .offcanvas-start는 왼쪽의 오프캔버스를 숨깁니다.
  • .offcanvas-end는 오른쪽의 오프캔버스를 숨깁니다.
  • .offcanvas-top는 위쪽의 오프캔버스를 숨깁니다.
  • .offcanvas-bottom은 아래쪽의 오프캔버스를 숨깁니다.

닫기 버튼에 data-bs-dismiss="offcanvas" 속성을 추가해 JavaScript 기능으로 감춥니다.

데이터 속성 사용하기

토글

요소에 data-bs-toggle="offcanvas"와 data-bs-target 또는 href를 추가하면 하나의 offcanvas 요소에 대한 제어가 자동으로 할당됩니다. data-bs-target 속성은 오프캔버스를 적용할 CSS 선택자를 허용합니다. offcanvas 요소에 offcanvas 클래스를 추가해야 합니다. 기본적으로 열리게 하려면 show 클래스를 추가하세요.

해제

해제는 아래와 같이 offcanvas 내에서 버튼의 data-bs-dismiss 속성을 사용하여 수행할 수 있습니다.

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

또는 아래와 같이 data-bs-target을 사용하여 offcanvas 외부의 버튼에서도 수행할 수 있습니다:

<button type="button" class="btn-close" data-bs-dismiss="offcanvas" data-bs-target="#my-offcanvas" aria-label="Close"></button>
모달을 해제하는 두 가지 방법을 모두 지원하지만 모달 외부에서 해제하는 것은 ARIA Authoring Practices Guide dialog (modal) pattern과 일치하지 않습니다. 문제가 생길 수도 있다는 점에 주의하세요.

JavaScript 사용하기

이처럼 수동으로 활성화 합니다:

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

옵션

옵션은 데이터 속성이나 자바스크립트를 통해 전달할 수 있으므로 데이터-bs-에 옵션 이름을 추가할 수 있습니다(예: 데이터-bs-animation="{value}"). 데이터 속성을 통해 옵션을 전달할 때 옵션 이름의 대/소문자 유형을 ‘camelCase‘에서 ‘kebab-case‘로 변경해야 합니다. 예를 들어 data-bs-custom-class="beautifier" 대신 data-bs-customClass="beautifier"를 사용합니다.

Bootstrap 5.2.0부터 모든 컴포넌트는 간단한 컴포넌트 구성을 JSON 문자열로 저장할 수 있는 experimental 예약 데이터 속성 data-bs-config를 지원합니다. 요소에 data-bs-config='{"delay":0,"title":123}' 및 data-bs-title="456" 속성이 있는 경우 최종 title 값은 456이 되며 별도의 데이터 속성이 data-bs-config에 지정된 값을 재정의합니다. 또한 기존 데이터 속성에는 data-bs-delay='{"show":0,"hide":150}'와 같은 JSON 값을 저장할 수 있습니다.

The final configuration object is the merged result of data-bs-config, data-bs-, and js object where the latest given key-value overrides the others.

이름 유형 기본값 설명
backdrop boolean 또는 string static true 오프캔버스가 열려 있는 동안, body에 배경을 적용합니다. Alternatively, specify static for a backdrop which doesn’t close the offcanvas when clicked.
keyboard boolean true escape키가 눌려지면 오프캔버스를 닫습니다.
scroll boolean false 오프캔버스를 여는 동안 body 스크롤링을 허용합니다.

메소드

All API methods are asynchronous and start a transition. They return to the caller as soon as the transition is started, but before it ends. In addition, a method call on a transitioning component will be ignored. Learn more in our JavaScript docs.

콘텐츠를 오프캔버스 요소로 액티브하게 합니다. 옵션의 object를 받습니다.

아래의 예시처럼 생성자를 사용해 오프캔버스의 인스턴스를 만들 수 있습니다:

const bsOffcanvas = new bootstrap.Offcanvas('#myOffcanvas')
Method Description
dispose Destroys an element’s offcanvas.
getInstance Static method which allows you to get the offcanvas instance associated with a DOM element.
getOrCreateInstance Static method which allows you to get the offcanvas instance associated with a DOM element, or create a new one in case it wasn’t initialized.
hide Hides an offcanvas element. Returns to the caller before the offcanvas element has actually been hidden (i.e. before the hidden.bs.offcanvas event occurs).
show Shows an offcanvas element. Returns to the caller before the offcanvas element has actually been shown (i.e. before the shown.bs.offcanvas event occurs).
toggle Toggles an offcanvas element to shown or hidden. Returns to the caller before the offcanvas element has actually been shown or hidden (i.e. before the shown.bs.offcanvas or hidden.bs.offcanvas event occurs).

이벤트

Bootstrap의 오프캔버스 클래스는 오프캔버스 기능에 연결하기 위한 몇 가지 이벤트를 공개하고 있습니다.

Event type Description
hide.bs.offcanvas This event is fired immediately when the hide method has been called.
hidden.bs.offcanvas This event is fired when an offcanvas element has been hidden from the user (will wait for CSS transitions to complete).
hidePrevented.bs.offcanvas This event is fired when the offcanvas is shown, its backdrop is static and a click outside of the offcanvas is performed. The event is also fired when the escape key is pressed and the keyboard option is set to false.
show.bs.offcanvas This event fires immediately when the show instance method is called.
shown.bs.offcanvas This event is fired when an offcanvas element has been made visible to the user (will wait for CSS transitions to complete). 
const myOffcanvas = document.getElementById('myOffcanvas')
myOffcanvas.addEventListener('hidden.bs.offcanvas', event => {
  // do something...
})