Drawer

npm install @vrembem/drawer

@use "@vrembem/drawer";

Drawer provides two JavaScript entries depending on how you want to register the custom element.

// Register the <vb-drawer> tag as a side-effect 
import "@vrembem/drawer/define";

// Import the element class directly
import { Drawer } from "@vrembem/drawer";

// Define the element yourself under a custom namespace
customElements.define("vb-drawer", Drawer);

Options

Once registered, Drawer is available as a <vb-drawer> custom element with a small Sass module for styles. Behavior is controlled through element attributes, while output and default values are controlled through Sass config and design token CSS variables.

Attributes

The custom element observes the following attributes. Changes made after the element is connected are applied automatically.

id (required)

Used to identify the drawer. The internal <dialog> element is given an id of [id]-modal, which is the value that triggers should target with the commandfor invoker API.

breakpoint

The viewport width that switches the drawer between static and modal states. Accepts a breakpoint key (e.g. md, lg, etc), or any valid CSS length.

position

The modal dialog position. Accepts top, right, bottom, or left values that apply modal--pos-[key] modifiers.

Sass

Drawer comes with the following Sass configuration options that can be set using either the config module or Sass with clause methods.

@use "@vrembem/drawer" with (
  $config: (
    // Sets the default breakpoint for drawers
    // @type string | number
    "breakpoint": "md",

    // Set the default position of modal drawers
    // @type string
    "position": "left"
  )
);

Design tokens

Drawer uses design token CSS variables to provide default values for custom element options.

--vb-drawer-breakpoint

md

--vb-drawer-position

left

Basic usage

The <vb-drawer> custom element wraps any content that should render inline when the viewport is at or above the breakpoint and inside a modal dialog when it's below. Once registered, the element manages the internal <dialog> structure, authors only need to provide the children.

Every drawer requires a unique id. Triggers open and close the modal state using the native command and commandfor attributes, targeting [id]-modal — the id of the dialog the drawer creates internally.

<button command="show-modal" commandfor="[unique-id]-modal">
  ...
</button>

<vb-drawer id="[unique-id]">
  ...
</vb-drawer>

The panel component is a great fit for structuring drawer content and works in both the static and modal layouts. Apply the panel class to the <vb-drawer> element and compose its elements inside.

<button command="show-modal" commandfor="custom-drawer-modal">
  Show modal
</button>

<vb-drawer id="custom-drawer" class="panel">
  <div class="panel__header">
    <h2 class="panel__title">Drawer</h2>
    <button class="link" command="close" commandfor="custom-drawer-modal">
      Close
    </button>
  </div>
  <div class="panel__body">
    <p>This is the contents of a drawer...</p>
  </div>
  <div class="panel__footer">
    <p>Drawer footer</p>
  </div>
</vb-drawer>

How it works

When the viewport is at or above the breakpoint, the drawer's children render inline as normal document flow. When the viewport drops below the breakpoint, the element:

• Adds the is-modal class to the host element and collapses its layout box so it no longer affects surrounding flow.
• Moves its children into an internal <dialog> element with the closedby="any" attribute and the following classes:
  • modal
  • modal--drawer
  • modal--pos-[key]
  • panel
• Exposes the dialog as [id]-modal, so triggers can open and close it with the native command/commandfor attributes.

Switching back above the breakpoint reverses the process. Children are moved back inline and the dialog is closed if it was open.

Breakpoint

The breakpoint attribute defines when the drawer switches between the static and modal states of the drawer. This accepts a value in three forms:

• Breakpoint key — resolved from --vb-breakpoint-[key] design tokens (e.g. md, lg, or any custom key defined).
• Unitless numbers — treated as pixel values (e.g. 760 becomes 760px).
• CSS length values — passed through as-is (e.g. 48rem, 800px).

If omitted, defaults to the value of --vb-drawer-breakpoint.

Position

The position attribute controls which viewport edge the modal dialog anchors to when open. This maps directly to the modal--pos-[key] modifier applied to the internal dialog.

If omitted, defaults to the value of --vb-drawer-position.

Available values

• top
• right
• bottom
• left