Side sheets, one file.

API reference

Constructor & usage

Drawer.open(opts) builds a drawer from options and returns a handle — { el, close(result), update(opts) }. Strings passed as title/content are rendered as text; markup requires the explicit html: true opt-in.

Drawer.open({
  side: 'right',           // 'right' | 'left' | 'top' | 'bottom'
  title: 'Your cart',
  content: 'Text',         // string | DOM element | markup with {html: true}
  size: '360px',           // width for left/right, height for top/bottom
  buttons: [
    { label: 'Clear', onClick: function (h) {} },        // return false = stay open
    { label: 'Checkout', variant: 'primary', close: true }
  ],
  dismissible: true,       // Esc, backdrop click, and the ✕ button
  onOpen: function (h) {},
  onClose: function (result) {}  // result = the `close` value of the button used
})
// → handle: { el, close(result), update(opts) }

Enhance mode — new Drawer(target, opts) adopts an in-page element (selector or element) as the drawer's content and restores it where it came from — including its hidden attribute — on close or destroy(). .open({...}) merges per-call options over the constructor's.

var cart = new Drawer('#cart-panel', { side: 'right', title: 'Cart' })
cart.open()                    // .open({...extra}) merges per-call options
cart.close()                   // cart.isOpen() → boolean
cart.destroy()                 // restores the element, drops the instance

Drawer.create(el, opts)        // constructor sugar → instance
Drawer.get(el)                 // → instance | null

No JS at all? See declarative init — data-vdr-open triggers are wired automatically on load.

Options

All keys of Drawer.defaults can be changed globally (Drawer.defaults.side = 'left') or passed per call. The options below the defaults are per-call only.

buttons entry shape:

Instance & handle methods

Instances come from new Drawer(target, opts) / Drawer.create(); handles come from Drawer.open() (and handle.el is the root <dialog>/<div> element).

Statics & helpers

Events & callbacks

The drawer communicates through option callbacks; it does not dispatch any DOM CustomEvents. (Internally it listens to the native <dialog> cancel/close events so platform-initiated closes stay in sync.)

Declarative init

<button data-vdr-open="#cart-panel">Cart</button>

<div id="cart-panel" hidden data-vdr-title="Your cart"
     data-vdr-side="right" data-vdr-size="380px">
  … <button data-vdr-close>Done</button>
</div>

Triggers present at load are wired automatically on DOMContentLoaded; call Drawer.autoInit(root?) for triggers added later. A trigger is only bound once, and one bad target does not abort init for the rest of the page.

Theming

Resolution order — a per-call theme or Drawer.defaults.theme of 'light'/'dark' pins the theme. Otherwise: the shared VC engine when the family core is loaded; else <html data-theme> / data-bs-theme → a .dark/.light class on <html> → prefers-color-scheme. Open drawers re-resolve live — a MutationObserver watches those attributes/classes and a media query listener watches the OS scheme.

All colors are CSS custom properties, defined unsalted on .vdr (dark values on .vdr[data-theme=dark]) so page overrides keep working:

CSS isolation — drawers render as class="vdr vc1 vdr-right" and every structural rule ships salted (.vdr.vc1 .vdr-panel { … }), so host-page design systems can't override them, while the unsalted --vdr-* variable definitions above stay overridable. Set a custom token with Drawer.salt = 'acme' before the first drawer, or disable salting with Drawer.salt = false. With the VC core loaded, VC.config({ accent: '#b45309' }) themes drawers and the rest of the family in one call.

Headless — Drawer.defaults.styles = false (or per-call styles: false) never injects CSS; you keep the full behavior (focus trap, scroll lock, stacking, ARIA) and style the markup contract yourself. Our stylesheet is a starting point: Drawer.css (string, rendered with the current salt) or dist/drawer.css (file).

dialog.vdr.vdr-right.vdr-has-title.vdr-in[data-theme="dark"]   ← .vdr-out while leaving
  .vdr-panel                    ← slides; inline width/height from `size`
    .vdr-head
      .vdr-title                ← only when `title` given (else .vdr-head-spacer)
      .vdr-x                    ← only when dismissible
    .vdr-body
      .vdr-msg                  ← string content (adopted elements go here raw)
    .vdr-foot                   ← only when `buttons` given
      .vdr-btn.vdr-btn-primary

Accessibility

The root is a native <dialog> opened with showModal() where supported (an identical fallback overlay otherwise, which gets an explicit role="dialog"). Either way it carries aria-modal="true" and aria-labelledby pointing at the title — or aria-label from the ariaLabel option / labels.dialog when there is no title.

Initial focus: [autofocus] → first focusable in the body → primary footer button → any footer button → the panel itself (tabindex="-1"). Tab is trapped inside — by the native top layer, or by a manual cycle on the fallback path — and focus returns to the opener once the exit animation finishes. Body scroll is locked while any drawer is open, with scrollbar-width compensation so the page never shifts. Drawers stack; Esc closes only the top-most. Animations honor prefers-reduced-motion.