Surfaces

Stable - @kikita-labs/ui v2.0.0

Drawer

Typed modal edge panel opened imperatively via kuiDrawer(), not rendered as a bound component instance. Built on Angular CDK Overlay. Use it for secondary workflows that keep page context visible: filters, detail panels, edit forms, navigation panels, and mobile action sheets.

Import

Import the inject-function factory and drawer-host contract types from the published package entrypoint.

drawer.ts
import {
  KUI_DRAWER_CONTEXT,
  KuiButton,
  KuiDrawerContext,
  KuiDrawerHost,
  kuiDrawer,
} from '@kikita-labs/ui';

// Import runtime styles once, application-wide:
import '@kikita-labs/ui/styles';

Usage

Open in Playground

Implement KuiDrawerHost on your drawer component, inject KUI_DRAWER_CONTEXT to read data and close, then create a typed opener with kuiDrawer() and call it with data to open. The returned observable emits the typed result once and completes.

<div class="basic-drawer-example">
  <button kuiButton type="button" (click)="edit()">Edit item</button>
  @if (lastResult()) {
    <p class="basic-drawer-example__result">Last result: {{ lastResult() }}</p>
  }
</div>

Sides

side selects the edge the drawer docks to and enters from: right (default), left, bottom, or top. Left/right drawers size by width; top/bottom drawers size by height.

<div class="drawer-sides-example">
  @for (side of sides; track side) {
    <button kuiButton type="button" shape="outline" (click)="open(side)">{{ side }}</button>
  }
</div>

Sizes

size selects a width preset for left/right drawers and a height preset for top/bottom drawers: sm, md (default), lg, full, or auto. auto sizes the panel to its content (min 320px width for left/right, min 200px height for top/bottom).

<div class="drawer-sizes-example">
  @for (size of sizes; track size) {
    <button kuiButton type="button" shape="outline" (click)="open(size)">{{ size }}</button>
  }
</div>

Provider defaults

Set defaults.drawer once for the application or for a subtree. Each option resolves as local input > defaults.drawer.<option> > built-in default.

import { provideKikitaUi } from '@kikita-labs/ui';

export const appConfig: ApplicationConfig = {
  providers: [
    provideKikitaUi({
      defaults: {
        drawer: {
          /* options below */
        },
      },
    }),
  ],
};
NameTypeDefaultDescription
closableboolean — Shows the close button in the header.
side'right' | 'left' | 'bottom' | 'top' — Edge the drawer slides in from.
size'sm' | 'md' | 'lg' | 'full' | 'auto' — Drawer size preset.
closeOnBackdropClickboolean — Closes the drawer on a backdrop click.
closeOnEscapeboolean — Closes the drawer on Escape.
closeIconKuiIconGlyph — Icon of the close button. Takes precedence over defaults.icons.close. See Structural Icons.

Theming tokens

Set any of these on the component or an ancestor to restyle one part. Each token is optional: when it is not set, the part uses the role or scale token in the default column.

NameTypeDefaultDescription
--kui-drawer-colorCSS custom property--kui-color-textColor
--kui-drawer-title-colorCSS custom property--kui-color-textTitle color
--kui-drawer-subtitle-colorCSS custom property--kui-color-text-secondarySubtitle color
--kui-drawer-close-colorCSS custom property--kui-color-text-secondaryClose color
--kui-drawer-close-bg-hoverCSS custom property--kui-color-state-hoverClose background, hover
--kui-drawer-close-color-hoverCSS custom property--kui-color-textClose color, hover
--kui-drawer-body-colorCSS custom property--kui-color-text-secondaryBody color
NameTypeDefaultDescription
--kui-drawer-header-gapCSS custom property--kui-space-3Header gap
--kui-drawer-subtitle-font-sizeCSS custom property--kui-text-sm-sizeSubtitle font size
--kui-drawer-close-radiusCSS custom property--kui-radius-smClose corner radius
--kui-drawer-body-font-sizeCSS custom property--kui-text-sm-sizeBody font size
--kui-drawer-footer-gapCSS custom property--kui-space-2Footer gap

Messages

Every text the component owns (accessible names, visible words, announcements) is a typed message with an English default. Override it for the application with provideKikitaUi({ messages }), or for a subtree with provideKuiMessages.

NameTypeDefaultDescription
labelstring — Accessible name of a drawer that has no title. Default Drawer.

API

API, provider defaults (every KuiDrawerConfig field falls back to defaults.drawer) and tokens verified against @kikita-labs/ui v2.0.0 public typings.

NameTypeDefaultDescription
kuiDrawer(component, config?)(component: Type<TComponent>, config?: Omit<KuiDrawerConfig, "data">) => (data: TData) => Observable<TResult | undefined>-Inject-function factory. Call once per injection context to get a typed opener bound to that component.
KuiDrawerHost<TResult, TData>interface-Contract your drawer component implements. Requires a drawerContext property injected from KUI_DRAWER_CONTEXT.
KUI_DRAWER_CONTEXTInjectionToken<KuiDrawerContext<TResult, TData>>-Injected inside the drawer component to read data and close the drawer.
drawerContext.dataTData-Data passed via the opener call, e.g. openDrawer(data).
drawerContext.sideKuiDrawerSide-Drawer side resolved from KuiDrawerConfig.side, read-only.
drawerContext.sizeKuiDrawerSize-Drawer size preset resolved from KuiDrawerConfig.size, read-only.
drawerContext.closableboolean-Mirrors KuiDrawerConfig.closable. Informational only -- the container renders .kui-drawer-close itself when true.
drawerContext.close(result?)(result?: TResult) => void-Closes the drawer, optionally emitting a typed result to the opener subscription.
KuiDrawerConfig.dataTDataundefinedAvailable on the low-level config type; kuiDrawer() passes feature data through the returned opener function instead.
KuiDrawerConfig.side'right' | 'left' | 'bottom' | 'top''right'Edge from which the drawer enters and docks.
KuiDrawerConfig.size'sm' | 'md' | 'lg' | 'full' | 'auto''md'Width for left/right drawers, height for top/bottom drawers. 'auto' sizes to content (min 320px width for left/right, min 200px height for top/bottom).
KuiDrawerConfig.closeOnBackdropClickbooleantrueCloses the drawer on backdrop click. Disable for required actions.
KuiDrawerConfig.closeOnEscapebooleantrueCloses the drawer on Escape. Disable for required actions.
KuiDrawerConfig.closablebooleantrueShows the .kui-drawer-close button the container renders automatically, absolutely positioned top-right of the panel.
KuiDrawerRef<TResult>class-Return type of kuiDrawer(component, config). Calling it with data opens the drawer and returns Observable<TResult | undefined>.
.kui-drawer-header / .kui-drawer-title / .kui-drawer-subtitleCSS classes-Header structure classes. .kui-drawer-title is wired as aria-labelledby automatically when present.
.kui-drawer-body / .kui-drawer-footerCSS classes-Scrollable content region and action row classes.
--kui-drawer-bgCSS custom property-Panel background color.
--kui-drawer-borderCSS custom property-Panel border color.
--kui-drawer-radiusCSS custom property-Panel corner radius.
--kui-drawer-backdrop-bgCSS custom property-Backdrop fill color.
--kui-drawer-width-sm / -md / -lgCSS custom properties-Width presets used by left/right drawers.
--kui-drawer-height-sm / -md / -lgCSS custom properties-Height presets used by top/bottom drawers.
--kui-drawer-duration-open / -closeCSS custom properties-Enter/exit animation durations.
KuiDrawerOptions / KuiModalSurfaceOptionsinterfaces-Shape of defaults.drawer (closable, side, size, closeOnBackdropClick, closeOnEscape, closeIcon), built on the base interface shared with the dialog. Options are read each time a drawer opens.

Accessibility

Drawer traps focus and matches native modal expectations while docked to a viewport edge.

  • The panel renders role="dialog" and aria-modal="true" automatically.
  • .kui-drawer-title is wired as aria-labelledby automatically when present in your content. Always include one.
  • Focus is trapped inside the drawer while open and returns to the opener on close.
  • Escape closes by default unless closeOnEscape: false; backdrop click closes by default unless closeOnBackdropClick: false. Disable both for required actions.
  • Backdrop dismissal only applies when the pointer interaction starts on the backdrop; selecting text or dragging from inside the drawer cannot close it accidentally.
  • The panel renders .kui-drawer-close itself, top-right of the header, when closable is true (the default); the header reserves space for it automatically. drawerContext.closable is retained for informational use only.

Migrating to 2.0

Consumer-visible changes of @kikita-labs/ui 2.0 for Drawer.

  • The imports are KuiButton and the rest of the renamed classes; ng update @kikita-labs/ui renames them. KuiDrawerContext, KUI_DRAWER_CONTEXT and kuiDrawer() keep their names.
  • Defaults come from defaults.drawer and are read each time a drawer opens; the close icon takes precedence over defaults.icons.close.
  • The backdrop and layers follow the new scrim and layer tokens, the close button reserves its space for titles rendered through a component portal, and the accessible name comes from the drawer messages.