Drawer

<sl-drawer> | SlDrawer
Since 1.0 stable

Drawers slide in from a container to expose additional options and information.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Close Open Drawer 
<sl-drawer label="Drawer" class="drawer-overview">
  Lorem ipsum dolor sit amet, consectetur adipiscing elit.
  <sl-button slot="footer" variant="primary">Close</sl-button>
</sl-drawer>

<sl-button>Open Drawer</sl-button>

<script>
  const drawer = document.querySelector('.drawer-overview');
  const openButton = drawer.nextElementSibling;
  const closeButton = drawer.querySelector('sl-button[variant="primary"]');

  openButton.addEventListener('click', () => drawer.show());
  closeButton.addEventListener('click', () => drawer.hide());
</script>

Examples

Slide in From Start

By default, drawers slide in from the end. To make the drawer slide in from the start, set the placement attribute to start.

This drawer slides in from the start. Close Open Drawer 
<sl-drawer label="Drawer" placement="start" class="drawer-placement-start">
  This drawer slides in from the start.
  <sl-button slot="footer" variant="primary">Close</sl-button>
</sl-drawer>

<sl-button>Open Drawer</sl-button>

<script>
  const drawer = document.querySelector('.drawer-placement-start');
  const openButton = drawer.nextElementSibling;
  const closeButton = drawer.querySelector('sl-button[variant="primary"]');

  openButton.addEventListener('click', () => drawer.show());
  closeButton.addEventListener('click', () => drawer.hide());
</script>

Slide in From Top

To make the drawer slide in from the top, set the placement attribute to top.

This drawer slides in from the top. Close Open Drawer 
<sl-drawer label="Drawer" placement="top" class="drawer-placement-top">
  This drawer slides in from the top.
  <sl-button slot="footer" variant="primary">Close</sl-button>
</sl-drawer>

<sl-button>Open Drawer</sl-button>

<script>
  const drawer = document.querySelector('.drawer-placement-top');
  const openButton = drawer.nextElementSibling;
  const closeButton = drawer.querySelector('sl-button[variant="primary"]');

  openButton.addEventListener('click', () => drawer.show());
  closeButton.addEventListener('click', () => drawer.hide());
</script>

Slide in From Bottom

To make the drawer slide in from the bottom, set the placement attribute to bottom.

This drawer slides in from the bottom. Close Open Drawer 
<sl-drawer label="Drawer" placement="bottom" class="drawer-placement-bottom">
  This drawer slides in from the bottom.
  <sl-button slot="footer" variant="primary">Close</sl-button>
</sl-drawer>

<sl-button>Open Drawer</sl-button>

<script>
  const drawer = document.querySelector('.drawer-placement-bottom');
  const openButton = drawer.nextElementSibling;
  const closeButton = drawer.querySelector('sl-button[variant="primary"]');

  openButton.addEventListener('click', () => drawer.show());
  closeButton.addEventListener('click', () => drawer.hide());
</script>

Contained to an Element

By default, drawers slide out of their containing block, which is usually the viewport. To make a drawer slide out of a parent element, add the contained attribute to the drawer and apply position: relative to its parent.

Unlike normal drawers, contained drawers are not modal. This means they do not show an overlay, they do not trap focus, and they are not dismissible with Escape. This is intentional to allow users to interact with elements outside of the drawer.

The drawer will be contained to this box. This content won’t shift or be affected in any way when the drawer opens. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Close
Toggle Drawer 
<div
  style="position: relative; border: solid 2px var(--sl-panel-border-color); height: 300px; padding: 1rem; margin-bottom: 1rem;"
>
  The drawer will be contained to this box. This content won't shift or be affected in any way when the drawer opens.

  <sl-drawer label="Drawer" contained class="drawer-contained" style="--size: 50%;">
    Lorem ipsum dolor sit amet, consectetur adipiscing elit.
    <sl-button slot="footer" variant="primary">Close</sl-button>
  </sl-drawer>
</div>

<sl-button>Toggle Drawer</sl-button>

<script>
  const drawer = document.querySelector('.drawer-contained');
  const openButton = drawer.parentElement.nextElementSibling;
  const closeButton = drawer.querySelector('sl-button[variant="primary"]');

  openButton.addEventListener('click', () => (drawer.open = !drawer.open));
  closeButton.addEventListener('click', () => drawer.hide());
</script>

Custom Size

Use the --size custom property to set the drawer’s size. This will be applied to the drawer’s width or height depending on its placement.

This drawer is always 50% of the viewport. Close Open Drawer 
<sl-drawer label="Drawer" class="drawer-custom-size" style="--size: 50vw;">
  This drawer is always 50% of the viewport.
  <sl-button slot="footer" variant="primary">Close</sl-button>
</sl-drawer>

<sl-button>Open Drawer</sl-button>

<script>
  const drawer = document.querySelector('.drawer-custom-size');
  const openButton = drawer.nextElementSibling;
  const closeButton = drawer.querySelector('sl-button[variant="primary"]');

  openButton.addEventListener('click', () => drawer.show());
  closeButton.addEventListener('click', () => drawer.hide());
</script>

Scrolling

By design, a drawer’s height will never exceed 100% of its container. As such, drawers will not scroll with the page to ensure the header and footer are always accessible to the user.

Scroll down and give it a try! 👇

Close Open Drawer 
<sl-drawer label="Drawer" class="drawer-scrolling">
  <div style="height: 150vh; border: dashed 2px var(--sl-color-neutral-200); padding: 0 1rem;">
    <p>Scroll down and give it a try! 👇</p>
  </div>
  <sl-button slot="footer" variant="primary">Close</sl-button>
</sl-drawer>

<sl-button>Open Drawer</sl-button>

<script>
  const drawer = document.querySelector('.drawer-scrolling');
  const openButton = drawer.nextElementSibling;
  const closeButton = drawer.querySelector('sl-button[variant="primary"]');

  openButton.addEventListener('click', () => drawer.show());
  closeButton.addEventListener('click', () => drawer.hide());
</script>

Header Actions

The header shows a functional close button by default. You can use the header-actions slot to add additional icon buttons if needed.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Close Open Drawer 
<sl-drawer label="Drawer" class="drawer-header-actions">
  <sl-icon-button class="new-window" slot="header-actions" name="arrow-up-right-from-square"></sl-icon-button>
  Lorem ipsum dolor sit amet, consectetur adipiscing elit.
  <sl-button slot="footer" variant="primary">Close</sl-button>
</sl-drawer>

<sl-button>Open Drawer</sl-button>

<script>
  const drawer = document.querySelector('.drawer-header-actions');
  const openButton = drawer.nextElementSibling;
  const closeButton = drawer.querySelector('sl-button[variant="primary"]');
  const newWindowButton = drawer.querySelector('.new-window');

  openButton.addEventListener('click', () => drawer.show());
  closeButton.addEventListener('click', () => drawer.hide());
  newWindowButton.addEventListener('click', () => window.open(location.href));
</script>

Preventing the Drawer from Closing

By default, drawers will close when the user clicks the close button, clicks the overlay, or presses the Escape key. In most cases, the default behavior is the best behavior in terms of UX. However, there are situations where this may be undesirable, such as when data loss will occur.

To keep the drawer open in such cases, you can cancel the sl-request-close event. When canceled, the drawer will remain open and pulse briefly to draw the user’s attention to it.

You can use event.detail.source to determine what triggered the request to close. This example prevents the drawer from closing when the overlay is clicked, but allows the close button or Escape to dismiss it.

This drawer will not close when you click on the overlay. Close Open Drawer 
<sl-drawer label="Drawer" class="drawer-deny-close">
  This drawer will not close when you click on the overlay.
  <sl-button slot="footer" variant="primary">Close</sl-button>
</sl-drawer>

<sl-button>Open Drawer</sl-button>

<script>
  const drawer = document.querySelector('.drawer-deny-close');
  const openButton = drawer.nextElementSibling;
  const closeButton = drawer.querySelector('sl-button[variant="primary"]');

  openButton.addEventListener('click', () => drawer.show());
  closeButton.addEventListener('click', () => drawer.hide());

  // Prevent the drawer from closing when the user clicks on the overlay
  drawer.addEventListener('sl-request-close', event => {
    if (event.detail.source === 'overlay') {
      event.preventDefault();
    }
  });
</script>

Customizing Initial Focus

By default, the drawer’s panel will gain focus when opened. This allows a subsequent tab press to focus on the first tabbable element in the drawer. If you want a different element to have focus, add the autofocus attribute to it as shown below.

Close Open Drawer 
<sl-drawer label="Drawer" class="drawer-focus">
  <sl-input autofocus placeholder="I will have focus when the drawer is opened"></sl-input>
  <sl-button slot="footer" variant="primary">Close</sl-button>
</sl-drawer>

<sl-button>Open Drawer</sl-button>

<script>
  const drawer = document.querySelector('.drawer-focus');
  const input = drawer.querySelector('sl-input');
  const openButton = drawer.nextElementSibling;
  const closeButton = drawer.querySelector('sl-button[variant="primary"]');

  openButton.addEventListener('click', () => drawer.show());
  closeButton.addEventListener('click', () => drawer.hide());
</script>

Slots

Name Description
(default) The drawer’s main content.
label The drawer’s label. Alternatively, you can use the label attribute.
header-actions Optional actions to add to the header. Works best with <sl-icon-button>.
footer The drawer’s footer, usually one or more buttons representing various options.

Learn more about using slots.

Properties

Name Description Reflects Type Default
modal Exposes the internal modal utility that controls focus trapping. To temporarily disable focus trapping and allow third-party modals spawned from an active Shoelace modal, call modal.activateExternal() when the third-party modal opens. Upon closing, call modal.deactivateExternal() to restore Shoelace’s focus trapping. - new Modal(this)
open Indicates whether or not the drawer is open. You can toggle this attribute to show and hide the drawer, or you can use the show() and hide() methods and this attribute will reflect the drawer’s open state. boolean false
label The drawer’s label as displayed in the header. You should always include a relevant label even when using no-header, as it is required for proper accessibility. If you need to display HTML, use the label slot instead. string ''
placement The direction from which the drawer will open. 'top' | 'end' | 'bottom' | 'start' 'end'
contained By default, the drawer slides out of its containing block (usually the viewport). To make the drawer slide out of its parent element, set this attribute and add position: relative to the parent. boolean false
noHeader
no-header 		Removes the header. This will also remove the default close button, so please ensure you provide an easy, accessible way for users to dismiss the drawer. boolean false
noScrollbar
no-scrollbar 		Removes the scrollbar. boolean false
updateComplete A read-only promise that resolves when the component has finished updating.

Learn more about attributes and properties.

Events

Name React Event Description Event Detail
sl-show Emitted when the drawer opens. -
sl-after-show Emitted after the drawer opens and all animations are complete. -
sl-hide Emitted when the drawer closes. -
sl-after-hide Emitted after the drawer closes and all animations are complete. -
sl-initial-focus Emitted when the drawer opens and is ready to receive focus. Calling event.preventDefault() will prevent focusing and allow you to set it on a different element, such as an input. -
sl-request-close Emitted when the user attempts to close the drawer by clicking the close button, clicking the overlay, or pressing escape. Calling event.preventDefault() will keep the drawer open. Avoid using this unless closing the drawer will result in destructive behavior such as data loss. { source: 'close-button' | 'keyboard' | 'overlay' }

Learn more about events.

Methods

Name Description Arguments
show() Shows the drawer. -
hide() Hides the drawer -

Learn more about methods.

Custom Properties

Name Description Default
--size The preferred size of the drawer. This will be applied to the drawer’s width or height depending on its placement. Note that the drawer will shrink to accommodate smaller screens.
--header-spacing The amount of padding to use for the header.
--body-spacing The amount of padding to use for the body.
--footer-spacing The amount of padding to use for the footer.

Learn more about customizing CSS custom properties.

Parts

Name Description
base The component’s base wrapper.
overlay The overlay that covers the screen behind the drawer.
panel The drawer’s panel (where the drawer and its content are rendered).
header The drawer’s header. This element wraps the title and header actions.
header-actions Optional actions to add to the header. Works best with <sl-icon-button>.
title The drawer’s title.
close-button The close button, an <sl-icon-button>.
close-button__base The close button’s exported base part.
body The drawer’s body.
footer The drawer’s footer.

Learn more about customizing CSS parts.

Animations

Name Description
drawer.showTop The animation to use when showing a drawer with top placement.
drawer.showEnd The animation to use when showing a drawer with end placement.
drawer.showBottom The animation to use when showing a drawer with bottom placement.
drawer.showStart The animation to use when showing a drawer with start placement.
drawer.hideTop The animation to use when hiding a drawer with top placement.
drawer.hideEnd The animation to use when hiding a drawer with end placement.
drawer.hideBottom The animation to use when hiding a drawer with bottom placement.
drawer.hideStart The animation to use when hiding a drawer with start placement.
drawer.denyClose The animation to use when a request to close the drawer is denied.
drawer.overlay.show The animation to use when showing the drawer’s overlay.
drawer.overlay.hide The animation to use when hiding the drawer’s overlay.

Learn more about customizing animations.

Dependencies

This component automatically imports the following dependencies.

  • <sl-icon>
  • <sl-icon-button>