Accessible bottom sheets and side panels for JavaScript, TypeScript and browser-based frameworks. No framework runtime or peer dependency required.
Demo · Examples · Documentation · Changelog
- Installation
- Quick start
- HTML / CDN
- Capabilities
- API at a glance
- Documentation
- Changelog
- AI agent skill
- License
npm install @samline/drawerpnpm add @samline/drawerbun add @samline/drawerPackage tooling requires Node.js 20+; browser output targets ES2020.
Import the stylesheet once in your application entrypoint:
import '@samline/drawer/style.css'Create a trigger, load the runtime stylesheet and give the panel its own positioning and appearance. Keep the returned controller: it owns opening, updates and cleanup.
<button id="open-filters" type="button" aria-haspopup="dialog">Open filters</button>import { createDrawer } from '@samline/drawer'
import '@samline/drawer/style.css'
import './drawer.css'
const drawer = createDrawer({
triggerElement: document.getElementById('open-filters'),
title: 'Filters',
content: 'Choose what you want to see.',
contentClassName: 'drawer-panel',
overlayClassName: 'drawer-overlay',
closeButton: { icon: '×', ariaLabel: 'Close filters' },
autoFocus: true,
}).drawer-overlay {
position: fixed;
inset: 0;
z-index: 100;
background: rgb(0 0 0 / 45%);
}
.drawer-panel {
position: fixed;
bottom: 0;
left: 0;
right: 0;
z-index: 100;
display: flex;
flex-direction: column;
box-sizing: border-box;
max-height: 90dvh;
padding: 1.5rem;
border-radius: 1.5rem 1.5rem 0 0;
background: white;
color: #24212b;
}
.drawer-panel [data-drawer-body] {
flex: 0 1 auto;
min-height: 0;
overflow-y: auto;
overscroll-behavior: contain;
}
.drawer-panel [data-drawer-close] {
flex-shrink: 0;
margin: 0.75rem 0 0 auto;
}The trigger opens the drawer; Escape, the backdrop and the close button dismiss it. Programmatic actions use the same owned instance:
drawer.setOpen(true)
drawer.update({ content: 'Your filters are ready.' })
drawer.setOpen(false)
// When the owning component or page leaves:
drawer.destroy()Load matching versioned runtime CSS and JavaScript, then replace the import with window.Drawer.createDrawer. Keep the same panel stylesheet and controller lifecycle.
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@samline/drawer@6.0.1/dist/style.css" />
<script src="https://cdn.jsdelivr.net/npm/@samline/drawer@6.0.1/dist/browser/drawer.global.js"></script>Pin the version in production, or self-host the same matching files. ESM/CommonJS are module formats; CDN or self-hosted files are delivery choices. The optional @samline/drawer/browser module exports a Drawer namespace with the same functions and no global side effect.
- Top, bottom, left and right panels, with matching consumer CSS.
- Native pointer dragging, handle-only dragging, snap points and programmatic snap selection.
- Modal focus containment, Escape/backdrop dismissal, background isolation and focus restoration.
- Independent non-modal panels and optional overlays.
- Parent/child drawers, shared scroll ownership and optional background scaling.
- Focus-gated mobile keyboard positioning and viewport handling.
- Dynamic content, lifecycle callbacks and observable state.
Working examples include forms, long content, nested panels and controlled snap sizes. Framework integrations covers React, Vue, Svelte, Astro, Shopify and WordPress using this same API.
Strings are plain text. Pass an HTMLElement or a factory returning one for custom UI; native templates are useful when fresh DOM is needed on each open. Keep persistent form data in application state. Supply an accessible title or label, label your inputs and provide a usable close action. Reading-only scroll regions need a named keyboard focus target. See content, styling and accessibility.
| API | Purpose |
|---|---|
createDrawer() |
Controller factory |
setOpen(), update(), setActiveSnapPoint() |
Controller commands |
getSnapshot(), subscribe() |
State and observation |
destroy() |
Cleanup |
getDrawer(), getDrawers(), getParentDrawer(), getChildDrawers() |
Registry queries |
destroyDrawers() |
Registry cleanup |
createDrawerController() |
State-only factory |
| Entrypoint | When to use |
|---|---|
@samline/drawer |
DOM and state-only factories, queries, cleanup and types for ESM or CommonJS. |
@samline/drawer/browser |
Browser module with a Drawer namespace and no global side effect. |
@samline/drawer/browser/global |
Standalone script that defines window.Drawer. |
@samline/drawer/style.css |
Required runtime layout and motion stylesheet. |
- Each
createDrawer()creates an independent instance. Omitted ids are generated; supply an id only for explicit lookup or parent relationships. - Explicit duplicate ids throw. Use
drawer.update()to change an existing instance. - Closing preserves the instance for reopening; destroying releases its registry entry, listeners, subscriptions, timers and owned effects.
- Destruction is final: stale handles cannot recreate a drawer or affect a new instance with the same id. Repeated
destroy()is harmless; other methods on a destroyed controller throw. setOpen(),update()andsetActiveSnapPoint()return the resulting snapshot.subscribe()fires immediately and returns an unsubscribe function.
import { createDrawer, getDrawer, getDrawers, destroyDrawers } from '@samline/drawer'
const filters = createDrawer({ id: 'filters', title: 'Filters' })
getDrawer('filters') === filters // true
getDrawer('missing') // null; does not create
Object.keys(getDrawers()) // ['filters']
// On whole-application teardown, when you own every registered instance:
destroyDrawers()getDrawers() returns a fresh object containing the same stable controller objects. getParentDrawer(id) and getChildDrawers(id) inspect nested relationships. Prefer a local controller when a component already owns it.
createDrawerController() is the advanced state-only API. It does not register, render, trap focus or lock scrolling. Its setOpen, update, setActiveSnapPoint, getSnapshot, subscribe and destroy methods follow the same state/disposal contract.
The package includes declarations. Import VanillaDrawerOptions/VanillaDrawerController for DOM integrations and CommonDrawerOptions/CommonDrawerController for state-only work. The TypeScript reference lists snapshot, direction, content, snap point and callback types.
Read the documentation for the full guides and API contracts, and explore working examples with complete and separate source files for both loading modes.
| Guide | What it covers |
|---|---|
| Getting started | Installation and the first owned drawer. |
| Configuration | Options, content, styling and accessibility. |
| Framework integrations | React, Vue, Svelte, Astro, Shopify and WordPress. |
| TypeScript | Public option, controller, snapshot and callback types. |
Read CHANGELOG.md or the published changelog for release history and explicitly marked breaking and behavior changes. Review the notes before upgrading.
V5 removes redundant factories and id-based mutators, unifies updates, makes creation explicit and destruction terminal. See Breaking changes and replacements before upgrading v4 code. Historical method URLs explain their replacement.
The Drawer skill describes v5 integration, lifecycle, content and host ownership. Pass it to an agent or install it using a skills-compatible tool. Verify the installed package version before applying its guidance.
The maintained repository source and website download are the same file.
Download SKILL.md into a drawer/ folder in your agent's supported skill directory. For agents that discover project skills from .agents/skills/:
mkdir -p .agents/skills/drawer
curl --fail --location https://samline.github.io/drawer/skills/drawer/SKILL.md \
--output .agents/skills/drawer/SKILL.mdWhen working from this repository, copy skills/drawer/SKILL.md instead. Keep the filename SKILL.md; discovery paths and invocation syntax depend on the agent.
MIT — LICENSE.md.