Reference

Options

Every Drawer option, accepted value and default, including modal behavior, renderable content, gestures, snap points and accessible naming.

createDrawer(options?) accepts VanillaDrawerOptions, which extends the headless CommonDrawerOptions state surface with DOM, content, trigger, and class options. Pass only the fields you need.

import { createDrawer } from '@samline/drawer'

const drawer = createDrawer({
  id: 'filters',
  direction: 'bottom',
  title: 'Filters',
  content: 'Body',
  closeButton: true,
})

Signature

interface CommonDrawerOptions {
  id?: CommonDrawerId
  parentId?: CommonDrawerId
  open?: boolean
  defaultOpen?: boolean
  onOpenChange?: (open: boolean) => void
  onClose?: () => void
  onAnimationEnd?: (open: boolean) => void
  onActiveSnapPointChange?: (snapPoint: CommonDrawerSnapPoint | null) => void
  onDragChange?: (percentageDragged: number) => void
  onReleaseChange?: (open: boolean) => void
  dismissible?: boolean
  modal?: boolean
  overlay?: boolean
  nested?: boolean
  direction?: CommonDrawerDirection
  snapPoints?: CommonDrawerSnapPoint[]
  fadeFromIndex?: number
  activeSnapPoint?: CommonDrawerSnapPoint | null
  closeThreshold?: number
  scrollLockTimeout?: number
  shouldScaleBackground?: boolean
  setBackgroundColorOnScale?: boolean
  handleOnly?: boolean
  fixed?: boolean
  disablePreventScroll?: boolean
  repositionInputs?: boolean
  snapToSequentialPoint?: boolean
  preventScrollRestoration?: boolean
  noBodyStyles?: boolean
  autoFocus?: boolean
  preventCycle?: boolean
}

Renderable content

The content, title, and description slots all accept the same shape: VanillaRenderable. Every example in this section uses content; the same rules apply to title and description.

type VanillaRenderable = string | number | HTMLElement | (() => HTMLElement) | null | undefined
Form What happens Example
string Mounted as a text node inside the slot. Safe for plain copy. content: 'Drawer body'
number Mounted as a text node. Useful for numeric badges. title: 3
HTMLElement Moved (not cloned) into the slot. The runtime does not own the element; do not append it elsewhere while the drawer owns it. content: formElement
() => HTMLElement The thunk is invoked once per dialog DOM build (mount on open, rebuild on option-driven remount) and must return an element. Lazy presence will re-invoke it on every reopen. content: () => buildForm()
undefined Omits title/description slots and renders no body content. description: undefined
null Renders no content, but title: null or description: null still creates an empty ARIA-referenced slot. Prefer omission when no slot should exist. content: null
import { createDrawer } from '@samline/drawer'

// 1. Plain string.
createDrawer({ id: 'a', content: 'Hello' })

// 2. Number.
createDrawer({ id: 'b', title: 3, content: 'Tag' })

// 3. Pre-built element (moved into the dialog).
const form = document.createElement('form')
form.innerHTML = '<input name="q" /><button>Search</button>'
createDrawer({ id: 'c', content: form })

// 4. Lazy thunk — re-invoked each time the dialog subtree is rebuilt.
createDrawer({
  id: 'd',
  content: () => {
    const node = document.createElement('div')
    node.className = 'lazy'
    node.textContent = new Date().toLocaleTimeString()
    return node
  },
})

// 5. Empty body. The [data-drawer-body] wrapper still mounts.
createDrawer({ id: 'e' })

Notes:

  • Move semantics: when you pass an HTMLElement, the runtime adopts it. Closing or destroying removes its ancestor subtree, so the element becomes detached from the document but remains available through your JavaScript reference. Reappend it yourself before reuse. Do not pass one connected instance to two drawers.
  • Lazy presence: the dialog subtree is unmounted on close, so a thunk re-runs every time the user reopens. Use this to refresh dynamic content, or capture expensive work outside the thunk.
  • Factory return: a thunk must return an HTMLElement. A different return value does not throw; it renders no content.
  • data-drawer-body: content is mounted directly into [data-drawer-body]. The body wrapper is always created while the dialog is mounted; title and description slots are conditional children of it.
  • Drag opt-out: any descendant inside the content can opt out of starting a drawer drag with data-drawer-no-drag.

See Recipes → Custom HTML content for end-to-end patterns.

Field reference

Common fields

Every field on CommonDrawerOptions. The example column shows the smallest realistic usage of the field.

Field Type Effective default Runtime behavior Example
id string generated unique id Explicit ids must be non-empty and unique. An omitted id creates an independent instance. Ids cannot be changed through update(). id: 'filters'
parentId string undefined Relates a child to a registered parent. Opening a child opens its ancestor chain; closing or destroying a parent closes or recursively destroys its children. Self-references and indirect cycles throw a TypeError. parentId: 'account'
open boolean undefined Explicit open state. open takes precedence over defaultOpen. Creating an initially open drawer mounts it without an entrance animation. open: true
defaultOpen boolean false Fallback initial state when open is undefined. An initially open first render also skips the entrance animation; opening a previously closed host animates. defaultOpen: true
onOpenChange (open: boolean) => void undefined Fires after a real open-state transition and after the controller contains the new state. No-op writes do not call it. onOpenChange(open) { log(open) }
onClose () => void undefined Fires immediately before a true to false state transition, so the snapshot is still open inside this callback. Destroying an open drawer does not call it. onClose() { cleanup() }
onAnimationEnd (open: boolean) => void undefined Timer-based notification 500 ms after an open-state transition. A newer transition cancels the prior timer, and destroy cancels it. It is not a DOM animationend event. onAnimationEnd(open) { log(open) }
onActiveSnapPointChange (snapPoint: number | string | null) => void undefined Fires after a runtime-driven snap change from drag release, handle cycling, or the post-close reset to the first snap. Direct setActiveSnapPoint() calls do not echo this callback. onActiveSnapPointChange(s) { setSnap(s) }
onDragChange (percentageDragged: number) => void undefined Fires on accepted pointer moves. The value is normalized against the rendered drawer dimension (or current snap interval) and can exceed 1 when dragged beyond a full dimension. onDragChange(p) { setDragProgress(p) }
onReleaseChange (open: boolean) => void undefined Fires after an accepted drag release: false when release closes, true when it resets or settles at a snap. Programmatic close and overlay clicks do not fire it. onReleaseChange(keptOpen) { log(keptOpen) }
dismissible boolean true Enables Escape, overlay mouse-up, drag-close, and last-snap handle dismissal. Programmatic methods and the optional built-in close button can still close when false. dismissible: false
modal boolean true Modal drawers trap focus, isolate background branches with inert/aria-hidden, and acquire scroll effects. false omits those behaviors. Neither mode writes body.style.pointerEvents. modal: false
overlay boolean same as modal Controls backdrop rendering independently. Use modal: false, overlay: true for a local dismissible backdrop without focus trapping, document isolation, or body scroll locking. overlay: true
nested boolean false Internal nested-layout flag. createDrawer() and update() set it automatically when parentId exists. Set parentId to establish a relationship; nested: true alone does not create one. nested: true
direction 'top' | 'bottom' | 'left' | 'right' 'bottom' Selects entrance/exit side, close gesture, drag axis, snap math, and scale transform axis. All four directions support drag-to-dismiss. direction: 'right'
snapPoints Array<number | string> [] Numbers are container fractions (0.5 is 50%). Strings use parseInt as pixels: '120.9px' becomes 120, '50%' becomes 50px, and '1rem' becomes 1px. Values are not validated; use finite, ordered, unique values. snapPoints: ['180px', '420px', 1]
fadeFromIndex number last snap index First snap index where the overlay is visible. If omitted with snap points, the runtime resolves it to snapPoints.length - 1. fadeFromIndex: 1
activeSnapPoint number | string | null snapPoints[0] ?? null Current snap value. Use an exact member of snapPoints; values are matched with strict equality and are not validated. A non-member disables normal release/cycle indexing. Close resets it to the first snap after 500 ms. activeSnapPoint: '180px'
closeThreshold number 0.25 For snap-free drawers, fraction of the rendered height/width required for a low-velocity release to dismiss. Snap-point releases use the separate snap policy. closeThreshold: 0.5
scrollLockTimeout number 100 Millisecond cooldown after scrollable content blocks a drag, preventing the next pointer gesture from being captured immediately. scrollLockTimeout: 200
shouldScaleBackground boolean false Scales, translates, rounds, and clips the first [data-drawer-wrapper] as soon as the drawer opens. Dragging toward close moves it back toward normal. shouldScaleBackground: true
setBackgroundColorOnScale boolean true With background scaling, sets the body background black while an owner is open and may write a translucent wrapper background during drag. Pass false to opt out of those color writes. setBackgroundColorOnScale: false
handleOnly boolean false Restricts drag starts to the built-in handle and renders that handle even when showHandle is omitted. handleOnly: true
fixed boolean false When the focused-input viewport pipeline runs, also writes a calculated drawer height. Since repositionInputs defaults to true, fixed: true normally writes both height and bottom offset. fixed: true
disablePreventScroll boolean false Disables the modal body-scroll prevention pipeline (desktop overflow/padding compensation or the iOS touch lock). It does not mean “no body styles”; see noBodyStyles. disablePreventScroll: true
repositionInputs boolean true Attaches an open-only visualViewport.resize listener when available. Layout changes are focus-gated: a keyboard-producing input, textarea, or editable element must be focused inside the drawer before the opening resize is handled. repositionInputs: false
snapToSequentialPoint boolean false For releases under 40% of the drawer dimension, restricts a high-velocity swipe to the adjacent snap. Longer releases still choose the closest snap and can skip points. snapToSequentialPoint: true
preventScrollRestoration boolean false Acquires global history.scrollRestoration = 'manual' ownership while open. The original value returns after the final owner closes or is destroyed. preventScrollRestoration: true
noBodyStyles boolean false Suppresses scale-background body color and Safari fixed-body positioning. It does not disable the baseline modal scroll lock; use disablePreventScroll for that. noBodyStyles: true
autoFocus boolean false Modal focus always moves inside. false focuses the dialog; true focuses the first visible focusable descendant and falls back to the dialog. autoFocus: true
preventCycle boolean false Disables handle click-to-cycle while retaining handle drag behavior. preventCycle: true

Vanilla-only options

interface VanillaDrawerOptions extends CommonDrawerOptions {
  container?: HTMLElement | null
  triggerElement?: HTMLElement | null
  triggerText?: string
  showHandle?: boolean
  handleClassName?: string
  handleAriaLabel?: string
  ariaLabel?: string
  ariaLabelledBy?: string
  ariaDescribedBy?: string
  title?: VanillaRenderable
  titleVisuallyHidden?: boolean
  description?: VanillaRenderable
  descriptionVisuallyHidden?: boolean
  content?: VanillaRenderable
  overlayClassName?: string
  contentClassName?: string
  closeButton?: boolean | { className?: string; icon?: string | Element; ariaLabel?: string }
}
Field Type Effective default Runtime behavior Example
container HTMLElement | null document.body Preferred mount target. The runtime appends a dedicated per-id host inside it and uses its bounding rect for snap-point fractions. Multiple drawers sharing a container remain isolated. container: document.getElementById('region')
triggerElement HTMLElement | null undefined Consumer-owned external element whose click opens the id. Its listener persists while closed, rebinds on update, and is removed on destroy. The runtime does not add aria-controls or aria-expanded; manage those attributes if needed. triggerElement: document.getElementById('open-filters')
triggerText string undefined Creates a built-in <button data-drawer-vanilla-trigger aria-haspopup="dialog"> in the per-id host. Its aria-expanded follows the open state. It persists while open, closed and during exit, updates in place, and is removed when cleared or destroyed. triggerText: 'Open filters'
showHandle boolean false Renders the built-in handle while dialog content is present. handleOnly also renders it. showHandle: true
handleClassName string undefined Class assigned to the built-in handle. handleClassName: 'my-handle'
handleAriaLabel string 'Change drawer position' Accessible name for the handle when it can cycle snap points. A handle without snap points, or with preventCycle, is hidden from keyboard and assistive technology and carries no name. handleAriaLabel: 'Resize filters'
ariaLabel string drawer id when no title Sets aria-label. When both title and ariaLabel are absent, the normalized drawer id is used so the dialog is always named. It does not create a proxy title slot. ariaLabel: 'Filters'
ariaLabelledBy string generated with title Used unchanged. With title, the runtime assigns this id to the built-in title slot; without title, you must provide that id elsewhere in your content/document. If omitted with a title, <drawer-id>-title is generated. ariaLabelledBy: 'filters-title'
ariaDescribedBy string generated with description Used unchanged. With description, the runtime assigns this id to that slot; without a description, you must provide the target. If omitted with a description, <drawer-id>-description is generated. ariaDescribedBy: 'filters-desc'
title VanillaRenderable undefined Visible title-slot content unless titleVisuallyHidden is true. See Renderable content. title: 'Filters'
titleVisuallyHidden boolean false Applies the built-in visually hidden inline styles to an existing title slot. It has no effect when title is omitted. titleVisuallyHidden: true
description VanillaRenderable undefined Description-slot content. See Renderable content. description: 'Refine the result set'
descriptionVisuallyHidden boolean true Applies the built-in visually hidden styles to the description slot. descriptionVisuallyHidden: false
content VanillaRenderable undefined Main body content. The open dialog skeleton and empty body slot still mount when this is omitted. See Renderable content. content: formElement
overlayClassName string undefined Class assigned to the overlay. overlayClassName: 'drawer-overlay'
contentClassName string undefined Class assigned to [data-drawer]. contentClassName: 'drawer-panel'
closeButton boolean | object false Renders <button data-drawer-close> after the body. true uses class drawer-close-button, an SVG X icon in currentColor, and label Close; an object overrides className, icon, and ariaLabel. Its click stops propagation and closes directly. closeButton: { className: 'absolute top-5 right-5' }

VanillaRenderable is string | number | HTMLElement | (() => HTMLElement) | null | undefined. Elements are moved into the dialog. A thunk is invoked once per dialog DOM build, so an option update that rebuilds the open subtree can invoke it again.

Updating and clearing options

Options are shallow-merged through one method: drawer.update() accepts state and DOM settings and returns the resulting snapshot. While open, only open, activeSnapPoint, and callback changes can reconcile without rebuilding the dialog. Other changes tear down and rebuild the open subtree, which can re-run content thunks, detach supplied elements, and move focus.

Optional fields do not share one universal reset value, especially with TypeScript’s exactOptionalPropertyTypes. Supported explicit clears include:

Option Clear with
triggerElement, container null
content, title, description null (note that null title/description retain empty slots)
snapPoints []
activeSnapPoint null
triggerText, class names ''
closeButton false

There is no typed generic “unset” operation for every shallow-merged optional field, including parentId. If an integration must remove such a stored option, destroy and recreate that id with the desired configuration.

Close-button option shape

The object passed to closeButton has its own option surface, exported only via the VanillaDrawerOptions type (the source name VanillaCloseButtonOptions is not a root type export).

Field Type Default Example
className string 'drawer-close-button' className: 'absolute top-5 right-5'
icon string | Element An SVG X in currentColor, inside a <span aria-hidden="true"> icon: '✕' or icon: xmarkElement
ariaLabel string 'Close' ariaLabel: 'Close filters'

The button’s click event stopPropagation()s so it does not bubble to the drawer’s content. The button is removed on re-mount and on drawer.destroy().

Presence and ownership

  • Calling createDrawer() creates one registered host per id even when closed.
  • A closed drawer has no overlay or dialog content. Only the host and optional built-in trigger persist.
  • Closing flips mounted nodes to data-state="closed", releases focus/scroll/viewport effects immediately, and removes overlay/content after the exit safety timeout. It does not unregister the id.
  • Shared scroll lock, document scroll behavior, history restoration, and scale-background effects are reference-counted or owner-stacked. One drawer closing cannot restore an effect still owned by another.
  • The runtime never reads or writes document.body.style.pointerEvents.
  • During the 600 ms closing window, updates reconcile the persistent trigger but do not fully rebuild the exiting dialog. Apply structural updates before closing or after reopening.
  • A destroyed controller is terminal. Its getSnapshot(), options access, commands and subscriptions throw. A DOM controller’s id stays readable, its element becomes null, and repeated destroy() is safe. A reused id belongs to a new independent controller.

Numeric defaults are root exports; see TypeScript → Numeric constants.