오프캔버스

// Offcanvas

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

작동 원리

오프캔버스는 JavaScript를 통해 토글하여 뷰포트의 왼쪽, 오른쪽, 위쪽 또는 아래쪽 가장자리에서 표시할 수 있는 사이드바 구성 요소입니다. 버튼 또는 앵커는 토글하는 특정 요소에 첨부되는 트리거로 사용되며, data 속성은 JavaScript를 호출하는 데 사용됩니다.

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

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

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

예시

오프캔버스 컴포넌트

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

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

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 스크롤

오프캔버스와 배경이 표시되면 <body> 요소의 스크롤이 비활성화됩니다. <body> 스크롤을 활성화하려면 data-bs-scroll 속성을 사용합니다.

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 스크롤 및 배경

배경이 보이면서도 <body> 스크롤을 활성화할 수 있습니다.

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>

정적 배경

배경을 정적으로 설정하면 오프캔버스 외부를 클릭해도 닫히지 않습니다.

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>

어두운 오프캔버스

v5.3.0부터 지원 중단 v5.2.0에서 추가됨

유틸리티를 사용하여 오프캔버스의 모양을 변경하여 어두운 탐색 모음과 같은 다양한 컨텍스트에 더 잘 어울리도록 합니다. 여기서는 어두운 오프캔버스를 적절히 스타일링하기 위해 .offcanvas에 .text-bg-dark를 추가하고 .btn-close-white를 .btn-close에 추가합니다. 내부에 드롭다운이 있는 경우 .dropdown-menu-dark를 .dropdown-menu에 추가하는 것도 고려하세요.

주의! 컴포넌트의 어두운 변형은 색상 모드가 도입된 v5.3.0에서 더 이상 사용되지 않습니다. 위에서 언급한 클래스를 수동으로 추가하는 대신 루트 요소, 부모 래퍼 또는 컴포넌트 자체에 data-bs-theme="dark"를 설정하세요.

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>

반응형

v5.2.0에서 추가됨

반응형 오프캔버스 클래스는 지정된 중단점 아래에서 뷰포트 외부의 콘텐츠를 숨깁니다. 해당 중단점 위에서는 내부 콘텐츠가 정상적으로 작동합니다. 예를 들어 .offcanvas-lg는 오프캔버스에서 lg 중단점 아래의 콘텐츠를 숨기지만 lg 중단점 위의 콘텐츠는 표시합니다.

Resize your browser to show the responsive offcanvas toggle.

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>

각 중단점마다 반응형 오프캔버스 클래스를 사용할 수 있습니다.

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

배치

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

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

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

...

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>

접근성

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

CSS

변수

v5.2.0에서 추가됨

Bootstrap의 진화하는 CSS 변수 접근 방식의 일환으로, 이제 오프캔버스는 향상된 실시간 사용자 지정을 위해 .offcanvas에서 로컬 CSS 변수를 사용합니다. CSS 변수의 값은 Sass를 통해 설정되므로 Sass 사용자 정의도 계속 지원됩니다.

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 다이얼로그 (모달) 패턴과 일치하지 않습니다. 문제가 생길 수도 있다는 점에 주의하세요.

JavaScript 사용하기

다음과 같이 수동으로 활성화할 수 있습니다:

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

옵션

옵션은 데이터 속성이나 JavaScript를 통해 전달할 수 있으므로 data-bs-에 옵션 이름을 추가할 수 있습니다(예: data-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 값을 저장할 수 있습니다.

최종 구성 개체는 data-bs-config, data-bs-, js object의 병합된 결과로, 주어진 최신 key-value가 다른 key-value를 재정의합니다.

이름	유형	기본값	설명
`backdrop`	boolean 또는 string `static`	`true`	오프캔버스가 열려 있는 동안, body에 배경을 적용합니다. 또는 클릭해도 오프캔버스가 닫히지 않는 배경에 static`을 지정할 수 있습니다.
`keyboard`	boolean	`true`	Esc 키가 눌려지면 오프캔버스를 닫습니다.
`scroll`	boolean	`false`	오프캔버스를 여는 동안 body 스크롤링을 허용합니다.

메소드

모든 API 메서드는 비동기식이며 전환을 시작합니다. 전환이 시작되는 즉시 호출자에게 반환되지만 전환이 끝나기 전에 호출자에게 반환됩니다. 또한 전환 중인 컴포넌트에 대한 메서드 호출은 무시됩니다. JavaScript 문서에서 자세히 알아보세요.

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

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

const bsOffcanvas = new bootstrap.Offcanvas('#myOffcanvas')

메소드	설명
`dispose`	요소의 오프캔버스를 제거합니다.
`getInstance`	정적 메서드를 사용하여 DOM 요소와 연관된 오프캔버스 인스턴스를 가져올 수 있습니다.
`getOrCreateInstance`	정적 메서드를 사용하여 DOM 요소와 연결된 오프캔버스 인스턴스를 가져오거나 초기화되지 않은 경우 새 인스턴스를 생성할 수 있습니다.
`hide`	오프캔버스 요소를 숨깁니다. 오프캔버스 요소가 실제로 숨겨지기 전 (`hidden.bs.offcanvas` 이벤트가 발생하기 전)에 호출자에게 반환합니다.
`show`	오프캔버스 요소를 표시합니다. 오프 캔버스 요소가 실제로 표시되기 전 (`shown.bs.offcanvas` 이벤트가 발생하기 전)에 호출자에게 반환합니다.
`toggle`	오프캔버스 요소를 표시 또는 숨김으로 토글합니다. 오프캔버스 요소가 실제로 표시되거나 숨겨지기 전 (`shown.bs.offcanvas` 또는 `hidden.bs.offcanvas` 이벤트가 발생하기 전) 호출자에게 반환합니다.

이벤트

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

이벤트 유형	설명
`hide.bs.offcanvas`	이 이벤트는 `hide` 메서드가 호출되면 즉시 발생합니다.
`hidden.bs.offcanvas`	이 이벤트는 오프캔버스 요소가 사용자에게 숨겨졌을 때 발생합니다. (CSS 전환이 완료될 때까지 기다립니다)
`hidePrevented.bs.offcanvas`	이 이벤트는 오프캔버스가 표시되고 배경이 `static`이며 오프캔버스 외부에서 클릭이 수행될 때 발생합니다. 이 이벤트는 Esc 키를 누르고 `keyboard` 옵션이 `false`로 설정된 경우에도 발생합니다.
`show.bs.offcanvas`	이 이벤트는 `show` 인스턴스 메서드가 호출될 때 즉시 발생합니다.
`shown.bs.offcanvas`	이 이벤트는 오프캔버스 요소가 사용자에게 표시되었을 때 발생합니다. (CSS 전환이 완료될 때까지 기다립니다)

const myOffcanvas = document.getElementById('myOffcanvas')
myOffcanvas.addEventListener('hidden.bs.offcanvas', event => {
  // do something...
})