ki-fab-menu
@kimen/elements/ki-fab-menu- Source
- Agent reference
Use a FAB menu when one screen has two to six related actions, such as creating a message or scheduling an event.
<div style="display:grid;align-items:end;justify-items:end;min-block-size:12rem"><ki-fab-menu label="Create" scrim="false"> <ki-fab-menu-item value="message">New message</ki-fab-menu-item> <ki-fab-menu-item href="#event">New event</ki-fab-menu-item></ki-fab-menu></div>Give each item a visible label. Set its value to a stable command identifier
when your application handles ki-select. Without a value, the event reports
the trimmed item label. Items with href navigate as native links.
Enter, Space and ArrowDown open the menu at the first action. ArrowUp opens
it at the last action. Up and Down wrap, Home and End go to the first and last
actions, and Escape returns focus to the trigger. Tab continues through the
page’s focus order. Use close-label to localize the close button’s name.
Static menus need space above the trigger. For fixed placement, reserve
clearance for the FAB after your content and set
--ki-fab-mobile-nav-block-size when fixed navigation uses the same corner.
Use scrim="false" for an embedded example or to keep the background undimmed.
When to use: group related creation or screen actions behind one floating button.
When not to use: for a single primary action, long lists, or site navigation.
Properties & attributes
| Attribute | Property | Type | Default | Description |
|---|---|---|---|---|
close-label | closeLabel | string | 'Close menu' | Localized accessible name of the trigger when it becomes the close control. |
icon-name | iconName | string | 'plus' | Registered Lucide glyph for the closed trigger. The plus glyph ships with the component. |
label | label | string | – | Accessible name of the closed trigger and of the menu. |
open | open | boolean | false | Whether the action stack is open. Reflected when the user opens or dismisses it. |
position | position | "fixed" | "static" | 'static' | Static anchors to the host. Fixed anchors to the viewport's block-end inline-end corner. |
scrim | scrim | boolean | true | Dim the viewport and dismiss on a scrim click. Use the boolean property or scrim="false" to opt out. |
variant | variant | "primary" | "secondary" | "surface" | 'secondary' | Closed FAB surface. The open trigger always uses primary. |
Events
| Event | Detail type | Description |
|---|---|---|
ki-close | CustomEvent<void> | Emitted when the action stack closes. |
ki-open | CustomEvent<void> | Emitted when the action stack opens. |
ki-select | CustomEvent<KiFabMenuSelectDetail> | Emits the selected item's value or its trimmed label. Native links retain their destination. |
Slots
| Slot | Description |
|---|---|
| (default) | Two to six direct ki-fab-menu-item children, in top-to-bottom order. |
CSS parts
| Part | Description |
|---|---|
menu | The named action list above the trigger. |
scrim | The optional pointer-dismissible overlay behind the menu. |
trigger | The native floating button that opens and closes the menu. |
CSS custom properties
The public styling contract of ki-fab-menu: reassign these tokens at :root or on a subtree — never override internals.
| Token | Description |
|---|---|
--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-fab-backdrop-filter | Complete optional filter behind the FAB. |
--ki-fab-bg | Tinted secondary FAB fill. |
--ki-fab-bg-image | Optional layer painted over the FAB fill. |
--ki-fab-fg | Ink on the tinted secondary FAB. |
--ki-fab-font-family | Typeface for FAB labels. |
--ki-fab-forced-colors-border-width | Boundary width for the FAB in forced colors. |
--ki-fab-hover-shadow | FAB elevation for a pointer that can hover. |
--ki-fab-icon-size | Glyph size of the default FAB. |
--ki-fab-menu-gap | Gap between two stacked actions. |
--ki-fab-menu-scrim-backdrop-filter | Complete optional filter behind the scrim. |
--ki-fab-menu-scrim-bg | Dimming fill behind the open menu and its trigger. |
--ki-fab-menu-scrim-bg-image | Optional image painted above the scrim fill. |
--ki-fab-menu-trigger-gap | Gap between the last action and the FAB. |
--ki-fab-mobile-nav-block-size | Height to reserve for mobile navigation, excluding the safe-area inset. |
--ki-fab-offset | Fixed FAB gap to the viewport edge or mobile navigation. |
--ki-fab-primary-bg | Strong primary FAB fill. |
--ki-fab-primary-fg | Ink on the strong primary FAB. |
--ki-fab-radius | Corner radius of the default FAB size. |
--ki-fab-shadow | Resting FAB elevation. |
--ki-fab-size | Minimum FAB footprint in the default size. |
--ki-fab-surface-bg | Raised surface FAB fill. |
--ki-fab-surface-fg | Ink on the raised surface FAB. |
--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-offset | Gap between a focusable component and its keyboard focus ring. |
--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. |
When to use: as a direct child of ki-fab-menu, with a short, visible action label.
When not to use: for a standalone action, a form control, or a container of interactive content.
Properties & attributes
| Attribute | Property | Type | Default | Description |
|---|---|---|---|---|
href | href | string | undefined | – | A nonempty destination renders a native link and preserves relative URL resolution. |
icon-name | iconName | string | undefined | – | Registered Lucide glyph. Import the desired icon before rendering. |
value | value | string | undefined | – | Stable selection identifier. When omitted, the menu reports the trimmed visible label. |
Events
| Event | Detail type | Description |
|---|---|---|
ki-select | CustomEvent<KiFabMenuSelectDetail> | Local command selection for a direct action binding. Links use native navigation. |
Slots
| Slot | Description |
|---|---|
| (default) | The visible action label. |
CSS parts
| Part | Description |
|---|---|
control | The native action button or link. |
icon | The decorative glyph next to the label. |
CSS custom properties
The public styling contract of ki-fab-menu-item: reassign these tokens at :root or on a subtree — never override internals.
| Token | Description |
|---|---|
--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-fab-forced-colors-border-width | Boundary width for the FAB in forced colors. |
--ki-fab-menu-item-backdrop-filter | Complete optional filter behind the action. |
--ki-fab-menu-item-bg | Tinted surface of a floating action. |
--ki-fab-menu-item-bg-image | Optional image painted above the action fill. |
--ki-fab-menu-item-content-gap | Space between the action glyph and label. |
--ki-fab-menu-item-fg | Label and icon ink on the tinted action surface. |
--ki-fab-menu-item-font-family | Typeface for action labels. |
--ki-fab-menu-item-font-size | Text size for action labels. |
--ki-fab-menu-item-font-weight | Text weight of an action label. |
--ki-fab-menu-item-height | Minimum block size and inline target of an action. |
--ki-fab-menu-item-hover-shadow | Elevation of a hovered action. |
--ki-fab-menu-item-icon-size | Size of the glyph preceding an action label. |
--ki-fab-menu-item-line-height | Line height of an action label. |
--ki-fab-menu-item-padding-block | Block padding for a wrapping action label. |
--ki-fab-menu-item-padding-end | Inline-end padding of an action. |
--ki-fab-menu-item-padding-start | Inline-start padding of an action. |
--ki-fab-menu-item-radius | Pill radius of an action. |
--ki-fab-menu-item-shadow | Elevation of a resting action. |
--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-offset | Gap between a focusable component and its keyboard focus ring. |
--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. |