Skip to content
Kimenpre-v1documentation home
Color scheme

ki-drawer

Place a drawer at start or end to edit details beside a list. Use bottom for a short action sheet. The built-in Close button is available for every placement. A bottom sheet also closes on a downward swipe from its handle.

Theme for this example
Color scheme for this example
Edit incident Done
<ki-button type="button" onclick="this.nextElementSibling.show()">Edit incident</ki-button>
<ki-drawer heading="Edit incident">
<ki-input label="Title" value="Search index rebuild"></ki-input>
<ki-button slot="footer" variant="primary" type="button" onclick="this.closest('ki-drawer').close()">Done</ki-button>
</ki-drawer>

Provide a heading to name the drawer. When a modal drawer closes, focus returns to the previously focused trigger. Use modal="false" to keep the rest of the page interactive, and close-label to translate the built-in button.

The app can veto dismissal by calling preventDefault() on ki-close. Wire slotted actions to your app and call close() when their work is done. The size property overrides the themed 18rem side width or bottom height cap.

API reference

When to use: Edit an item beside its list or offer a short set of actions in a bottom sheet. Supply a heading and wire slotted actions in the application. Use non-modal mode if people need to interact with the page while editing.

When not to use: Menus, hover hints, permanent navigation, or work that needs a full page. For a short interrupting decision in the center, use ki-dialog.

Properties & attributes

AttributePropertyTypeDefaultDescription
close-labelcloseLabelstring | undefined'Close'Accessible name for the built-in Close button. Translate this for localized interfaces.
headingheadingstring–Title and accessible name. Provide a heading whenever the drawer opens.
modalmodalbooleantrueMakes the page behind the sheet inert. Set modal="false" for continued page interaction.
openopenbooleanfalseReflected live state. Setting it to false requests dismissal and may be vetoed.
placementplacement"bottom" | "end" | "start"'end'Logical edge. Use bottom for an action sheet with a swipe handle. Unknown values use end.
sizesizestring | undefined–Optional CSS length. Overrides the 18rem themed width or bottom height cap.

Events

EventDetail typeDescription
ki-closeCustomEvent<KiDrawerCloseDetail>Requests dismissal before the drawer closes. Call preventDefault() to keep it open, for example when edits are unsaved. The event carries the reason in detail.reason.

Methods

MethodDescription
close() => Promise<void>Requests dismissal. An application can veto it by canceling ki-close.
show() => Promise<void>Opens the sheet. A focused invoker receives focus again after modal dismissal.

Slots

SlotDescription
(default)The drawer's content, such as fields or a short list of actions.
footerOptional actions such as Save. Wire these in the application.
header-actionsOptional actions between the heading and Close button.

CSS parts

PartDescription
bodyThe scrollable content region.
closeThe built-in Close button.
dialogThe native sheet surface.
footerThe action row, collapsed when empty.
handleThe decorative bottom-sheet swipe handle.
headerThe heading and action layout.
headingThe visible title that names the sheet.

CSS custom properties

The public styling contract of ki-drawer: reassign these tokens at :root or on a subtree — never override internals.

TokenDescription
--ki-corner-controlDeprecated alias kept for pre-Fase-1 consumers; use ki.radius.md.
--ki-density-space-scaleMultiplies every scaled container padding and gap (card, dialog, alert, list, list item, select listbox, tab panel, tooltip).
--ki-density-target-minThe smallest pointer target any density may produce: 24 x 24 CSS px by default and in compact (WCAG 2.5.8 AA), 44 x 44 in touch (WCAG 2.5.5). It floors a shrinking control but never lifts what a control paints: a control painted smaller extends its target to it, invisibly; rows and tabs grow to it (spec 045 A1).
--ki-dialog-backdrop-bgcolor used by the dialog component for backdrop background.
--ki-dialog-divider-widthdimension used by the dialog component for the dividers under the heading and above the footer (Modal-header and Modal-actions 1px strokes). Zero removes them.
--ki-drawer-backdrop-filterComplete backdrop filter applied behind the drawer surface.
--ki-drawer-bgRaised surface color of the drawer.
--ki-drawer-bg-imageOptional image layered over the drawer surface.
--ki-drawer-close-sizePreferred size of the Close button before the density minimum.
--ki-drawer-fgForeground color on the drawer surface.
--ki-drawer-handle-colorColor of the bottom-sheet handle.
--ki-drawer-handle-sizeInline extent of the bottom-sheet handle.
--ki-drawer-handle-thicknessThickness of the bottom-sheet handle.
--ki-drawer-heading-font-familyTypeface of the drawer title.
--ki-drawer-radiusRadius of the corners on the inner edge of the drawer.
--ki-drawer-shadowResting elevation of the drawer.
--ki-drawer-sizeDefault inline size of a side sheet and block-size cap of a bottom sheet.
--ki-focus-ring-colorColour of the keyboard focus ring every focusable component draws: 3:1 or more against the page in every theme and scheme.
--ki-focus-ring-widthThickness of the keyboard focus ring every focusable component draws (its outline). One token instead of one per component, so a mode or a theme changes every ring at once.
--ki-layout-spacing-2xlThe 2xl spacing step for a stack or grid gap.
--ki-layout-spacing-mdThe md spacing step for a stack or grid gap.
--ki-layout-spacing-xlThe xl spacing step for a stack or grid gap.
--ki-motion-duration-fastFast interaction transition duration.
--ki-motion-duration-medium-1M3 md.sys.motion.duration.medium1 (250ms). onmars: MarsUI moderate step (240ms, 2x the 120ms base).
--ki-motion-easing-outDecelerating interaction transition easing curve.
--ki-outline-low-emsemantic color for outline low em.
--ki-surface-hover-overlay-inversesemantic color for surface hover overlay inverse.
--ki-surface-transparentTransparent surface backing for a background image that carries its own opacity.
--ki-typography-family-bodysemantic font family for typography family body.
--ki-typography-line-height-title-2semantic dimension for typography line height title 2.
--ki-typography-size-title-2semantic dimension for typography size title 2.
--ki-typography-weight-body-semiboldsemantic font weight for typography weight body semibold.

Workshop

Open ki-drawer in Storybook