Integration

Features & Props

One place to understand how tiny-drawer works, what the runtime lifecycle looks like, and which options or props are available in both the core and React packages.

How it works

The core package creates a drawer instance against a host container. Nothing touches the DOM until you create that instance on the client. From there, the drawer mounts its UI, manages open and close state, handles drag resizing or scroll-full expansion, and dispatches callbacks plus custom events from the original parent container.

The React package keeps that same behavior, but wraps it in a component and hook API. React still owns your state and children, while the wrapper creates and updates the underlying TinyDrawer instance inside effects.

1. Create

Choose the package, import its CSS, and create the drawer only on the client.

2. Configure

Set placement, size, drag limits, close behavior, parent mounting, scroll-full rules, and callbacks.

3. Control

Open or close it with instance methods, events, React state, refs, or the hook API.

Core package options

These options apply to new TinyDrawer(container, options) from the tiny-drawer package.

Option	Type	Default	How it works
`position`	"top" \| "right" \| "bottom" \| "left"	"bottom"	Controls which edge the drawer attaches to.
`size`	string \| number	"40%"	Default open size for the drawer.
`minSize`	string \| number	"20%"	Smallest size allowed during drag resize.
`maxSize`	string \| number	"90%"	Largest size allowed during drag resize.
`content`	string \| HTMLElement	undefined	Accepts HTML, text, selectors, or a real element.
`parentContainer`	string \| HTMLElement	undefined	Mounts the drawer host inside a specific parent element.
`themePrefix`	string	undefined	Adds prefixed theme classes such as acme-drawer.
`backdrop`	boolean	true	Shows or hides the backdrop layer.
`closeButton`	boolean	true	Renders the close button inside the drawer.
`closeOnBackdrop`	boolean	true	Closes only when the backdrop itself is clicked.
`outSideClickClose`	boolean	false	Closes when the user clicks outside the mounted parent or container boundary.
`closeOnEscape`	boolean	true	Enables keyboard escape to close.
`draggable`	boolean	true	Turns on the resize handle and pointer-driven drag behavior.
`onScrollFull`	boolean \| { backDrop?: boolean; drawer?: boolean; scrollTarget?: HTMLElement \| string \| null }	false	Disables drag and enables scroll-to-full behavior. Use an object in 1.2.0 to choose whether backdrop scroll, drawer scroll, or a custom scrollTarget can trigger fullscreen expansion.
`fullScreenGap`	string \| number	0	Keeps space from the opposite edge while scroll-full mode is active.
`animation`	boolean	true	Disables transitions when set to false.
`appendToBody`	boolean	true	Keeps the drawer mounted on document.body with fixed positioning.
`lastDragLocation`	boolean	true	Keeps the last dragged size after closing and reopening.
`className`	string	undefined	Adds custom classes to the drawer element.
`zIndex`	number	1050	Base stacking value for the drawer and backdrop.
`ariaLabel`	string	"Drawer"	Accessible dialog label.
`onOpen`	(instance) => void	undefined	Runs after the drawer opens.
`onClose`	(instance) => void	undefined	Runs after the drawer closes.
`onDragStart`	(instance) => void	undefined	Runs when resize dragging starts.
`onDrag`	(size, instance) => void	undefined	Runs during drag updates.
`onDragEnd`	(size, instance) => void	undefined	Runs when resize dragging ends.
`onDestroy`	(instance) => void	undefined	Runs when the instance is destroyed.

Methods

After you create an instance, these methods drive the drawer programmatically.

Method	How it works
`open()`	Opens the drawer and moves focus into it.
`close()`	Closes the drawer and restores focus when possible.
`toggle()`	Switches between open and closed state.
`destroy()`	Removes DOM, listeners, and runs destroy hooks.
`setContent(content)`	Replaces the drawer content with HTML or an element.
`setPosition(position)`	Moves the drawer to another edge.
`setSize(size)`	Applies a new size value.
`getSize()`	Returns the current size string.
`isOpen()`	Returns whether the drawer is currently open.

Custom events

The core package dispatches these events from the original parent container, which makes it easy to integrate with plain DOM code or analytics hooks.

Event	Detail
`tiny-drawer:open`	{ instance }
`tiny-drawer:close`	{ instance }
`tiny-drawer:drag-start`	{ instance }
`tiny-drawer:drag`	{ instance, size }
`tiny-drawer:drag-end`	{ instance, size }
`tiny-drawer:destroy`	{ instance }

React props

These props are available on the TinyDrawer component from tiny-drawer-react.

Prop	Type	Default	How it works
`open`	boolean	undefined	Controlled open state.
`defaultOpen`	boolean	false	Initial uncontrolled state.
`onOpenChange`	(open: boolean) => void	undefined	Receives state changes from user actions and imperative APIs.
`position`	DrawerPosition	vanilla default	Updates placement through instance.setPosition().
`size`	DrawerSizeValue	vanilla default	Updates size through instance.setSize().
`minSize`	DrawerSizeValue	vanilla default	Passed through to the core package.
`maxSize`	DrawerSizeValue	vanilla default	Passed through to the core package.
`parentContainer`	string \| HTMLElement \| null	null	Optional parent mount target for the underlying instance.
`themePrefix`	string	undefined	Passed through to the core package.
`backdrop`	boolean	undefined	Passed through to the core package.
`closeButton`	boolean	undefined	Passed through to the core package.
`closeOnBackdrop`	boolean	undefined	Passed through to the core package.
`outSideClickClose`	boolean	undefined	Closes the drawer when the user clicks outside its mounted boundary.
`closeOnEscape`	boolean	undefined	Passed through to the core package.
`draggable`	boolean	undefined	Passed through to the core package.
`onScrollFull`	boolean \| DrawerScrollFullOptions	undefined	Enables scroll-to-full behavior and supports the 1.2.0 object API with backDrop, drawer, and nested scrollTarget. In React, prefer a stable object reference instead of an inline object when the page re-renders often.
`fullScreenGap`	DrawerSizeValue	undefined	Controls the gap preserved while the drawer expands to full size.
`animation`	boolean	undefined	Passed through to the core package.
`appendToBody`	boolean	undefined	Passed through to the core package.
`lastDragLocation`	boolean	undefined	Passed through to the core package.
`className`	string	undefined	Custom class applied to the drawer element.
`zIndex`	number	undefined	Passed through to the core package.
`ariaLabel`	string	undefined	Passed through to the core package.
`children`	React.ReactNode	undefined	Rendered into the internal content portal.
`container`	string \| HTMLElement \| null	null	Uses an external host container when supplied.
`containerClassName`	string	undefined	Applied to the internal host container when one is rendered.
`containerStyle`	React.CSSProperties	undefined	Inline styles for the internal host container.
`destroyOnUnmount`	boolean	true	Controls whether the wrapper destroys the instance during unmount.
`restoreFocus`	boolean	true	Restores focus after close when possible.
`onOpen`	(instance) => void	undefined	Vanilla open callback passthrough.
`onClose`	(instance) => void	undefined	Vanilla close callback passthrough.
`onDragStart`	(instance) => void	undefined	Vanilla drag start callback passthrough.
`onDrag`	(size, instance) => void	undefined	Vanilla drag callback passthrough.
`onDragEnd`	(size, instance) => void	undefined	Vanilla drag end callback passthrough.
`onDestroy`	(instance) => void	undefined	Vanilla destroy callback passthrough.

Behavior notes

Bottom drawers grow upward, top drawers grow downward, left drawers grow rightward, and right drawers grow leftward. Percentage sizes resolve from the mounted parent container when embedded, and from the viewport when the drawer is body-mounted.

When onScrollFull is enabled, drag resizing is disabled and the drawer expands once the chosen scroll target moves beyond the top threshold. In 1.2.0, pass an object to onScrollFull when you want separate control over backDrop, drawer, and a nested scrollTarget. Use fullScreenGap to preserve space from the opposite edge.

In React, avoid writing onScrollFull={{ backDrop: true, drawer: true }}directly inside JSX when the parent re-renders frequently. That creates a fresh object every render, which can cause the wrapper to re-sync scroll-full behavior and lead to visible flicker in some layouts. Prefer a shared constant or useMemo().

Accessibility behavior includes role="dialog", aria-modal, escape-key close support, focus moving into the drawer on open, and focus restoration on close when possible.