Since Shoelace 2.0 Code stable Pattern Tentative Figma draft

Drawer

sl-drawer

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

Examples

Basic Drawer

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>

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

javascript:
  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());

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>

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

javascript:
  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());

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>

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

javascript:
  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());

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>

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

javascript:
  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());

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>

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.drawer-contained label="Drawer" contained=true style="--size: 50%;"
    | Lorem ipsum dolor sit amet, consectetur adipiscing elit.
    sl-button slot="footer" variant="primary"
      | Close
sl-button
  | Toggle Drawer

javascript:
  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());

Opening from Dropdown Menu

When opening a drawer from a sl-dropdown menu item triggered by a sl-button, wrap the button in a div and add slot="trigger" to the div rather than the button to prevent the drawer from skipping when opening.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Close
Dropdown
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-dropdown>
  <div slot="trigger"><sl-button caret>Dropdown</sl-button></div>
  <sl-menu>
    <sl-menu-item class="open-link">Open drawer</sl-menu-item>
  </sl-menu>
</sl-dropdown>

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

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

</script>

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

sl-dropdown
  div slot="trigger"
    sl-button caret=true Dropdown
    sl-menu
      sl-menu-item.open-link Open drawer

javascript:
  const drawer = document.querySelector(.drawer-overview);
  const openButton = drawer.querySelector(.open-link);
  const closeButton = drawer.querySelector(sl-button[variant=primary]);

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

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>

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

javascript:
  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());

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>

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

javascript:
  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());

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-top-right-on-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>

sl-drawer.drawer-header-actions label="Drawer"
  sl-icon-button.new-window slot="header-actions" name="arrow-top-right-on-square"
  | Lorem ipsum dolor sit amet, consectetur adipiscing elit.
  sl-button slot="footer" variant="primary" Close
sl-button Open Drawer

javascript:
  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));

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>

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

javascript:
  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();
  }
  });

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>

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

javascript:
  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());

Component Props

Property Default Details
modal new Modal(this)

—

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.

open false

boolean

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.

label ''

string

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.

placement 'end'

'top' | 'end' | 'bottom' | 'start'

The direction from which the drawer will open.
contained false

boolean

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.

noHeader
no-header 		false

boolean

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.

updateComplete A read-only promise that resolves when the component has finished updating.

Learn more about attributes and properties.

Slots

Name Details
(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.

Events

Name Name Name React Event Details
sl-show sl-show sl-show onSlShow

Emitted when the drawer opens.
sl-after-show sl-after-show sl-after-show onSlAfterShow

Emitted after the drawer opens and all animations are complete.
sl-hide sl-hide sl-hide onSlHide

Emitted when the drawer closes.
sl-after-hide sl-after-hide sl-after-hide onSlAfterHide

Emitted after the drawer closes and all animations are complete.
sl-initial-focus sl-initial-focus sl-initial-focus onSlInitialFocus

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 sl-request-close sl-request-close onSlRequestClose

{ source: 'close-button' | 'keyboard' | 'overlay' }

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.

Learn more about events.

Methods

Name Details
show()

Shows the drawer.
hide()

Hides the drawer

Learn more about methods.

Custom Properties

Name Details
--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.

CSS 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>