Drawer
Side-panel navigation drawer that integrates with the Origam layout grid. Supports rail/mini mode, expand-on-hover, temporary/persistent variants, touch drag, and four docking edges (left, right, top, bottom).
Structure
Anatomy
Visual breakdown of the component's internal structure with BEM class call-outs.
<origam-drawer> — 4 parts: ① root drawer panel (teleported into the layout grid), ② prepend zone (fixed header), ③ append zone (fixed footer), ④ scrollable content (#default slot).- 1.origam-drawer
- Root nav element. Teleported into
#layout-id .origam-layout__wrapperso it participates in the layout grid. Renders inline when no OrigamLayout ancestor exists. - 2.origam-drawer__prepend
- Fixed zone above the scrollable content. Rendered only when the #prepend slot is filled.
flex: noneso it does not participate in content scrolling. - 3.origam-drawer__append
- Fixed zone below the scrollable content. Rendered only when the #append slot is filled.
flex: none. - 4.origam-drawer__content
- Scrollable content area hosting the #default slot.
overflow-y: auto; fills remaining height between prepend and append.
API
Props
All props accepted by this component, with their type, default value and description.
- disableResizeWatcherbooleanfalse
- Prevents the drawer from auto-toggling between permanent and temporary based on the viewport width.
- disableRouteWatcherbooleanfalse
- Prevents the temporary drawer from automatically closing on Vue Router navigation.
- expandOnHoverbooleanfalse
- When combined with rail=true, expands the drawer to its full width on mouse hover and emits update:rail=false. Returns to rail on mouse leave.
- floatingbooleanfalse
- Removes the border on the open edge of the drawer.
- modelValuebooleantrue
- v-model binding for the open/close state. Defaults to true (drawer shown).
- permanentboolean | nullnull
- When true the drawer is always visible and cannot be dismissed. null = automatic (browser-width driven via resize watcher).
- railboolean | nullnull
- Collapses the drawer to rail (icon-only) width defined by railWidth. null means uncollapsed.
- railWidthnumber | string56
- Width in pixels when rail=true.
- temporarybooleanfalse
- Renders the drawer as a temporary overlay with a scrim. Clicking the scrim closes it.
- touchlessbooleanfalse
- Disables touch-drag to open/close the drawer.
- widthnumber | string256
- Full expanded width of the drawer in pixels.
- stickybooleanfalse
- Switches the drawer to position: sticky instead of absolute, so it scrolls with the page and sticks at the top when reaching its boundary.
- pushboolean | nullnull
- Whether the drawer reserves space in the layout grid, pushing adjacent toolbar/main/footer. null = derived from permanent (permanent drawers push, temporary drawers overlay).
- clippedboolean | nullnull
- When true the drawer slots below the AppBar instead of extending full height. null = resolved from HTML declaration order.
- attachboolean | string | Element | null
- tagstring'nav'
- HTML element at the root. Defaults to nav for semantic navigation drawers.
- idstring
- classstring | Array<string> | object
- stylestring | Array<string> | object | StyleValue
- borderboolean | number | string | TDirectionBoth | Array<TDirectionBoth>
- borderTopboolean | number | string
- borderLeftboolean | number | string
- borderBottomboolean | number | string
- borderRightboolean | number | string
- borderBlockboolean | number | string
- borderInlineboolean | number | string
- borderInlineStartboolean | number | string
- borderInlineEndboolean | number | string
- borderBlockStartboolean | number | string
- borderBlockEndboolean | number | string
- borderColorstring
- borderStylestring
- borderTopColorTColor
- borderRightColorTColor
- borderBottomColorTColor
- borderLeftColorTColor
- borderInlineStartColorTColor
- borderInlineEndColorTColor
- borderBlockStartColorTColor
- borderBlockEndColorTColor
- elevationTElevation
- Box-shadow elevation token. Overrides the default (none for permanent, lg for temporary).
- namestring
- orderstring | number
- absoluteboolean
- locationTDirectionBoth'left'
- Docking edge. Accepts "left", "right", "top", "bottom". Controls slide direction and border placement.
- roundedboolean | number | string | TRounded | null | undefined
- roundedTopRightboolean | number | string
- roundedTopLeftboolean | number | string
- roundedBottomLeftboolean | number | string
- roundedBottomRightboolean | number | string
- roundedStartStartboolean | number | string
- roundedStartEndboolean | number | string
- roundedEndStartboolean | number | string
- roundedEndEndboolean | number | string
- colorTColor
- bgColor
- Background color override for the drawer surface.
- densityTDensity
- paddingboolean | number | string
- paddingTopboolean | number | string
- paddingLeftboolean | number | string
- paddingBottomboolean | number | string
- paddingRightboolean | number | string
- paddingBlockboolean | number | string
- paddingInlineboolean | number | string
- paddingInlineStartboolean | number | string
- paddingInlineEndboolean | number | string
- paddingBlockStartboolean | number | string
- paddingBlockEndboolean | number | string
- marginboolean | number | string
- marginTopboolean | number | string
- marginLeftboolean | number | string
- marginBottomboolean | number | string
- marginRightboolean | number | string
- marginBlockboolean | number | string
- marginInlineboolean | number | string
- marginInlineStartboolean | number | string
- marginInlineEndboolean | number | string
- marginBlockStartboolean | number | string
- marginBlockEndboolean | number | string
- transitionboolean | string | TTransitionProps'origam-transition--drawer'
- Enter/leave transition name or config. Defaults to origam-transition--drawer (full-width slide). Pass false to disable.
- scrimboolean | stringtrue
- Shows a scrim overlay when the drawer is open in temporary mode. Pass a color string to customise the scrim color.
- activeboolean | IStateEffectConfig
- activeClassstring
- hoverboolean | IStateEffectConfig
- hoverClassstring
API
Slots
Content slots exposed by this component.
- #wrapper
- Replaces the entire inner layout (prepend + content + append wrapper). Use for fully custom drawer layouts.
- #default
- Main scrollable content area of the drawer (navigation list, links, etc.).
- #prepend
- Fixed content above the scrollable area. Typically the app logo or user avatar.
- #append
- Fixed content below the scrollable area. Typically settings or logout links.
API
Emits
Events emitted by this component.
- @update:railboolean
- Fired by expand-on-hover: true when hovered (expand), false when the cursor leaves (collapse back to rail).
- @update:modelValueany
- Fired when the open/close state changes (e.g. scrim click, route change, resize watcher).
API
Exposed members
Properties and methods accessible via template ref (defineExpose). Use them for programmatic control.
- <T extends object>(props: T, exclude?: string[]) => Partial<T>
- Utility to forward a filtered subset of props to child components.
- Ref<string>
- Reactive CSS string from drawerStyles. Used by OrigamDefaultsProvider.
- string
- Unique style-sheet ID for this drawer instance.
- () => void
- Injects the computed style sheet on mount.
- () => void
- Removes the injected style sheet on unmount.
- Ref<boolean>
- True once the style sheet has been injected.
Customisation
CSS variables
CSS custom properties exposed by this component. Override them to customise the component without losing theme compatibility.
- Background color of the drawer panel.
- Foreground (text/icon) color.
- Box shadow. Applied to shadow.lg automatically in temporary mode.
- Drawer panel width. Driven by the width prop and layout item styles (useLayoutItem).
- Duration of the open/close slide animation.
- Easing function for the open/close transition.
- Scrim overlay background color (temporary mode).
- Scrim opacity. Animates with drag progress during touch drag.
Inclusion
Accessibility
ARIA roles, keyboard navigation and focus management. Sourced from the real component template.
ARIA roles
Keyboard interactions
| Key | Action |
|---|---|
| Tab / Shift+Tab | Moves focus between interactive elements inside the drawer. |
| Escape | Closes the drawer when in temporary mode (if the overlay scrim is active). |
Notes
- The root element renders as <nav> by default (configurable via the tag prop). This gives it an implicit navigation landmark role, discoverable by screen reader landmark navigation.
- The root element carries aria-label set to the name prop (or "Navigation" as fallback). Provide a meaningful name prop when multiple navigation landmarks exist on the page.
- The scrim overlay in temporary mode is purely decorative and hidden from assistive technologies. It only handles click events to close the drawer.
Foundation
Design tokens
Excerpt from this component's token declarations — the --origam-<component>---<property> variables, declared in its hand-maintained token sheet with no build step.
- colorvar(--origam-color__surface---default)
- Drawer surface background color.
- shadowvar(--origam-shadow---none)
- Default shadow (none for permanent). Overridden to shadow.lg in temporary mode.
- durationvar(--origam-motion__duration---medium)
- Open/close animation duration.
- shadowvar(--origam-shadow---lg)
- Shadow applied when the drawer is in temporary mode to elevate it above the scrim.
- colorvar(--origam-color__overlay---scrim)
- Background of the scrim shown behind the temporary drawer.
- number0.2
- Scrim opacity in temporary mode. Tracks drag progress during touch open/close.
Interactive
Playground
Edit props live and see the component update in real time. The generated code snippet updates as you change values.
Rendering the live preview…
Usage
Examples
Ready-to-paste code snippets for your templates.
Permanent navigation drawer
Rail mode with expand-on-hover
Temporary (mobile) drawer