Drawer

<pc-drawer>

0.5.1

experimental

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

<pc-drawer label="Drawer" class="drawer-overview">
    This drawer contains supplementary content that is not required immediately, such as settings, contextual actions or secondary information related to the current view.

    <pc-button variant="plain" slot="footer" data-drawer="close">
        Close
    </pc-button>
</pc-drawer>

<pc-button>Open drawer</pc-button>

<script>
    const drawer = document.querySelector(".drawer-overview");
    const openButton = drawer.nextElementSibling;

    openButton.addEventListener("click", () => (drawer.open = true));
</script>

Code

Edit

Demos

Opening and closing drawers declaratively

You can open and close drawers with JavaScript by toggling the open attribute, but you can also do it declaratively. Add the data-drawer="open id" to any button on the page, where id is the id of the dialog you want to open.

<pc-drawer label="Drawer" id="drawer-open-declarative">
    This drawer is opened declaratively using a <code>data</code> attribute on a button outside of the component.

    <pc-button variant="plain" slot="footer" data-drawer="close">
        Close
    </pc-button>
</pc-drawer>

<pc-button data-drawer="open drawer-open-declarative">
    Open drawer
</pc-button>

Code

Edit

Similarly, you can add data-drawer="close" to a button inside of the drawer to tell it to close it.

<pc-drawer label="Drawer" id="drawer-dismiss-declarative">
    This drawer is dismissed using a declarative close trigger placed inside the drawer’s footer.

    <pc-button variant="plain" slot="footer" data-drawer="close">
        Close
    </pc-button>
</pc-drawer>

<pc-button data-drawer="open drawer-dismiss-declarative">
    Open drawer
</pc-button>

Code

Edit

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.

<pc-drawer label="Drawer" placement="start" class="drawer-placement-start">
    This drawer slides in from the start.

    <pc-button variant="plain" slot="footer" data-drawer="close">
        Close
    </pc-button>
</pc-drawer>

<pc-button>Open drawer</pc-button>

<script>
    const drawer = document.querySelector(".drawer-placement-start");
    const openButton = drawer.nextElementSibling;

    openButton.addEventListener("click", () => (drawer.open = true));
</script>

Code

Edit

Slide in from top

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

<pc-drawer label="Drawer" placement="top" class="drawer-placement-top">
    This drawer slides in from the top.

    <pc-button variant="plain" slot="footer" data-drawer="close">
        Close
    </pc-button>
</pc-drawer>

<pc-button>Open drawer</pc-button>

<script>
    const drawer = document.querySelector(".drawer-placement-top");
    const openButton = drawer.nextElementSibling;

    openButton.addEventListener("click", () => (drawer.open = true));
</script>

Code

Edit

Slide in from bottom

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

<pc-drawer label="Drawer" placement="bottom" class="drawer-placement-bottom">
    This drawer slides in from the bottom.

    <pc-button variant="plain" slot="footer" data-drawer="close">
        Close
    </pc-button>
</pc-drawer>

<pc-button>Open drawer</pc-button>

<script>
    const drawer = document.querySelector(".drawer-placement-bottom");
    const openButton = drawer.nextElementSibling;

    openButton.addEventListener("click", () => (drawer.open = true));
</script>

Code

Edit

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.

<pc-drawer label="Drawer" class="drawer-custom-size">
    This drawer is always 50 % of the viewport.

    <pc-button variant="plain" slot="footer" data-drawer="close">
        Close
    </pc-button>
</pc-drawer>

<pc-button>Open drawer</pc-button>

<script>
    const drawer = document.querySelector(".drawer-custom-size");
    const openButton = drawer.nextElementSibling;

    openButton.addEventListener("click", () => (drawer.open = true));
</script>

<style>
    .drawer-custom-size {
        --size: 50vw;
    }
</style>

Code

Edit

Scrolling

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

<pc-drawer label="Drawer" class="drawer-scrolling">
    <div
        style="
            padding: var(--pc-spacing-l);
            block-size: 150dvh;
            border: var(--pc-border-width-m) dashed
                var(--pc-color-neutral-border-normal);
            border-radius: var(--pc-border-radius-l);
        "
    >
        <p>Scroll down and give it a try! ⬇️</p>
    </div>

    <pc-button variant="plain" slot="footer" data-drawer="close">
        Close
    </pc-button>
</pc-drawer>

<pc-button>Open drawer</pc-button>

<script>
    const drawer = document.querySelector(".drawer-scrolling");
    const openButton = drawer.nextElementSibling;

    openButton.addEventListener("click", () => (drawer.open = true));
</script>

Code

Edit

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.

<pc-drawer label="Drawer" class="drawer-header-actions">
    <pc-button
        class="new-window"
        size="small"
        variant="plain"
        slot="header-actions"
    >
        <pc-icon
            library="default"
            icon-style="solid"
            name="arrow-up-right-from-square"
        ></pc-icon>
    </pc-button>

    This drawer includes an additional action in the header, which can be used for tasks such as opening related content in a new window.

    <pc-button variant="plain" slot="footer" data-drawer="close">
        Close
    </pc-button>
</pc-drawer>

<pc-button>Open drawer</pc-button>

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

    openButton.addEventListener("click", () => (drawer.open = true));
    newWindowButton.addEventListener("click", () => window.open(location.href));
</script>

Code

Edit

Prevent light dismissal

If you want to prevent the drawer from closing if the user clicks on the overlay, add the no-light-dismiss attribute.

<pc-drawer label="Drawer" class="drawer-no-light-dismiss" no-light-dismiss>
    This drawer will not close when you click on the overlay.

    <pc-button variant="plain" slot="footer" data-drawer="close">
        Close
    </pc-button>
</pc-drawer>

<pc-button>Open drawer</pc-button>

<script>
    const drawer = document.querySelector(".drawer-no-light-dismiss");
    const openButton = drawer.nextElementSibling;

    openButton.addEventListener("click", () => (drawer.open = true));
</script>

Code

Edit

Prevent drawer from closing

By default, drawers will close when the user clicks the close button, clicks the overlay or presses the Esc key. In most cases, the default behaviour is the best behaviour 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 pc-hide event. When cancelled, the drawer will remain open and pulse briefly to draw the user’s attention to it.

You can use event.detail.source to check what triggered the close request. In this example, the drawer will only close when a custom close button inside the footer is clicked. Clicking the overlay, pressing Esc or using the built‐in header close button will all be prevented.

<pc-drawer label="Drawer" class="drawer-deny-close">
    This drawer will only close if you click on the button below.

    <pc-button variant="plain" slot="footer" data-drawer="close">
        Close
    </pc-button>
</pc-drawer>

<pc-button>Open drawer</pc-button>

<script>
    const drawer = document.querySelector(".drawer-deny-close");
    const openButton = drawer.nextElementSibling;
    const closeButton = drawer.querySelector('pc-button[slot="footer"]');

    drawer.addEventListener("pc-hide", (event) => {
        if (event.detail.source !== closeButton) {
            event.preventDefault();
        }
    });

    openButton.addEventListener("click", () => (drawer.open = true));
</script>

Code

Edit

Customise 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.

<pc-drawer label="Drawer" class="drawer-focus">
    <pc-input
        placeholder="I will have focus when the drawer is opened"
        aria-label="I will have focus when the drawer is opened"
        autofocus
    ></pc-input>

    <pc-button variant="plain" slot="footer" data-drawer="close">
        Close
    </pc-button>
</pc-drawer>

<pc-button>Open drawer</pc-button>

<script>
    const drawer = document.querySelector(".drawer-focus");
    const openButton = drawer.nextElementSibling;

    openButton.addEventListener("click", () => (drawer.open = true));
</script>

Code

Edit

Properties

Name	Description	Default
`open`	Indicates whether or not the drawer is open. Toggle this attribute to show and hide the drawer. Type: `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. Type: `string`	`""`
`placement`	The direction from which the drawer will open. Type: `"top" \| "end" \| "bottom" \| "start"`	`"end"`
`noHeader` `no-header`	This 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. Type: `boolean`	`false`
`noLightDismiss` `no-light-dismiss`	Prevents clicks on the backdrop causing the drawer to close. Type: `boolean`	`false`
`updateComplete`	A read‐only promise that resolves when the component has finished updating.	‐

Learn more about customising animations.

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 `<pc-button>`.
`footer`	The drawer’s footer, usually one or more buttons representing various options.

Learn more about using slots.

Events

Name	Description	Event detail
`pc-show`	Emitted when the drawer opens.	‐
`pc-after-show`	Emitted after the drawer opens and all animations are complete.	‐
`pc-hide`	Emitted when the drawer closes.	`{ source: Element }`
`pc-after-hide`	Emitted after the drawer closes and all animations are complete.	‐

Learn more about events.

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.	`25rem`
`--header-spacing`	The amount of padding to use for the header.	`var(--pc-spacing-xl)`
`--body-spacing`	The amount of padding to use for the body.	`var(--pc-spacing-s) var(--pc-spacing-xl)`
`--footer-spacing`	The amount of padding to use for the footer.	`var(--pc-spacing-s) var(--pc-spacing-xl) var(--pc-spacing-xl)`

Learn more about customising custom properties.

Parts

Name	Description
`drawer`	The drawer’s `<dialog>` element.
`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 `<pc-button>`.
`title`	The drawer’s title.
`close-button`	The close button, a `<pc-button>`.
`close-button-base`	The close button’s exported `base` part.
`body`	The drawer’s body.
`footer`	The drawer’s footer.

Learn more about customising 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.

Learn more about customising animations.

Importing

If you’re using the autoloader or the standard loader, you can skip this section. But if you’re cherry picking, you can use any of the following snippets to import this component.

CDN (script tag)

CDN (import)

npm (import)

To manually import this component from the CDN, copy this code snippet and paste it in your HTML.

  <script type="module" src="https://cdn.jsdelivr.net/npm/placer-toolkit@1.0.0-alpha.3/cdn/components/drawer/drawer.js"></script> 

To manually import this component from the CDN, copy this code snippet and paste it in your JavaScript file.

  import "https://cdn.jsdelivr.net/npm/placer-toolkit@1.0.0-alpha.3/cdn/components/drawer/drawer.js"; 

To manually import this component from npm, copy this code snippet and paste it in your JavaScript file.

import "placer-toolkit/dist/components/drawer/drawer.js";

Dependencies

This component automatically imports these components:

Button