ki-drawer
@kimen/elements/ki-drawer- Source
- Agent reference
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.
<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
| Attribute | Property | Type | Default | Description |
|---|---|---|---|---|
close-label | closeLabel | string | undefined | 'Close' | Accessible name for the built-in Close button. Translate this for localized interfaces. |
heading | heading | string | – | Title and accessible name. Provide a heading whenever the drawer opens. |
modal | modal | boolean | true | Makes the page behind the sheet inert. Set modal="false" for continued page interaction. |
open | open | boolean | false | Reflected live state. Setting it to false requests dismissal and may be vetoed. |
placement | placement | "bottom" | "end" | "start" | 'end' | Logical edge. Use bottom for an action sheet with a swipe handle. Unknown values use end. |
size | size | string | undefined | – | Optional CSS length. Overrides the 18rem themed width or bottom height cap. |
Events
| Event | Detail type | Description |
|---|---|---|
ki-close | CustomEvent<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
| Method | Description |
|---|---|
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
| Slot | Description |
|---|---|
| (default) | The drawer's content, such as fields or a short list of actions. |
footer | Optional actions such as Save. Wire these in the application. |
header-actions | Optional actions between the heading and Close button. |
CSS parts
| Part | Description |
|---|---|
body | The scrollable content region. |
close | The built-in Close button. |
dialog | The native sheet surface. |
footer | The action row, collapsed when empty. |
handle | The decorative bottom-sheet swipe handle. |
header | The heading and action layout. |
heading | The 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.
| Token | Description |
|---|---|
--ki-corner-control | Deprecated alias kept for pre-Fase-1 consumers; use ki.radius.md. |
--ki-density-space-scale | Multiplies every scaled container padding and gap (card, dialog, alert, list, list item, select listbox, tab panel, tooltip). |
--ki-density-target-min | The 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-bg | color used by the dialog component for backdrop background. |
--ki-dialog-divider-width | dimension 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-filter | Complete backdrop filter applied behind the drawer surface. |
--ki-drawer-bg | Raised surface color of the drawer. |
--ki-drawer-bg-image | Optional image layered over the drawer surface. |
--ki-drawer-close-size | Preferred size of the Close button before the density minimum. |
--ki-drawer-fg | Foreground color on the drawer surface. |
--ki-drawer-handle-color | Color of the bottom-sheet handle. |
--ki-drawer-handle-size | Inline extent of the bottom-sheet handle. |
--ki-drawer-handle-thickness | Thickness of the bottom-sheet handle. |
--ki-drawer-heading-font-family | Typeface of the drawer title. |
--ki-drawer-radius | Radius of the corners on the inner edge of the drawer. |
--ki-drawer-shadow | Resting elevation of the drawer. |
--ki-drawer-size | Default inline size of a side sheet and block-size cap of a bottom sheet. |
--ki-focus-ring-color | Colour of the keyboard focus ring every focusable component draws: 3:1 or more against the page in every theme and scheme. |
--ki-focus-ring-width | Thickness 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-2xl | The 2xl spacing step for a stack or grid gap. |
--ki-layout-spacing-md | The md spacing step for a stack or grid gap. |
--ki-layout-spacing-xl | The xl spacing step for a stack or grid gap. |
--ki-motion-duration-fast | Fast interaction transition duration. |
--ki-motion-duration-medium-1 | M3 md.sys.motion.duration.medium1 (250ms). onmars: MarsUI moderate step (240ms, 2x the 120ms base). |
--ki-motion-easing-out | Decelerating interaction transition easing curve. |
--ki-outline-low-em | semantic color for outline low em. |
--ki-surface-hover-overlay-inverse | semantic color for surface hover overlay inverse. |
--ki-surface-transparent | Transparent surface backing for a background image that carries its own opacity. |
--ki-typography-family-body | semantic font family for typography family body. |
--ki-typography-line-height-title-2 | semantic dimension for typography line height title 2. |
--ki-typography-size-title-2 | semantic dimension for typography size title 2. |
--ki-typography-weight-body-semibold | semantic font weight for typography weight body semibold. |