ki-fab
@kimen/elements/ki-fab- Source
- Agent reference
Use one FAB per screen for a primary action such as Compose or New project.
Keep secondary and destructive actions with the content they affect. In a
desktop layout with a visible primary action, use ki-button.
<ki-fab label="New project" variant="primary" extended><svg slot="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true" focusable="false"> <path d="M5 12h14M12 5v14"></path></svg></ki-fab>Supply a localized label for the native control. The icon-only layout uses
it as its accessible name, and extended shows the same text next to the icon.
The icon slot takes decorative, noninteractive content and replaces the
glyph selected by icon-name. Import a named glyph before mounting the FAB.
import '@kimen/elements/icons/pencil';import { defineCustomElement } from '@kimen/elements/ki-fab';
defineCustomElement();<ki-fab label="Compose" icon-name="pencil"></ki-fab>The default size is md (56 px). Use lg (80 px) or xl (96 px) for greater
prominence. These dimensions assume a 16 px root font size. secondary is
the default tinted fill. primary uses the strongest fill and surface
uses a raised surface.
Without href, the FAB is a native button and Enter or Space activates it.
Set href for a native link that follows its destination on Enter.
Listen for the native click event to handle activation in your application.
Fixed placement
Keep the fixed FAB after the main content in the DOM. It sits at the viewport’s
bottom inline-end corner, accounting for the bottom safe area. On a screen with
fixed mobile navigation, set --ki-fab-mobile-nav-block-size on a shared
ancestor to the navigation’s block size excluding the safe area.
Reserve block-end space equal to the FAB size, the navigation’s block size, the bottom safe area, and two placement offsets. Use the same clearance as scroll padding so keyboard focus can move into the unobscured area.
<main class="compose-page"> <!-- Page content --></main><ki-fab label="Compose" icon-name="pencil" position="fixed" extended collapse-on-scroll></ki-fab>:root { --ki-fab-mobile-nav-block-size: var(--app-mobile-nav-height, 0px); --compose-clearance: calc( var(--ki-fab-size) + 2 * var(--ki-fab-offset) + var(--ki-fab-mobile-nav-block-size) + env(safe-area-inset-bottom, 0px) ); scroll-padding-block-end: var(--compose-clearance);}
.compose-page { padding-block-end: var(--compose-clearance);}This example uses the default size. For lg or xl, use the corresponding
FAB size when calculating the clearance. If the label wraps, reserve the
actual expanded height. Set --app-mobile-nav-height only while the fixed
navigation is visible.
With collapse-on-scroll, an extended FAB shows just its icon during downward
document scrolling and restores the label on upward scrolling. The same
control keeps focus and its name throughout. Reduced motion makes the change
immediate.
API reference
When to use: give a mobile screen one primary action, such as composing a draft or creating a project. Supply a descriptive label and a registered icon or decorative icon slot. Reserve page clearance for fixed placement, and leave the action binding unset for native link navigation.
When not to use: for secondary or destructive actions, for multiple actions on the same screen, or on a desktop screen that already has a visible primary ki-button.
Properties & attributes
| Attribute | Property | Type | Default | Description |
|---|---|---|---|---|
collapse-on-scroll | collapseOnScroll | boolean | false | Compact an extended FAB on viewport scroll down and restore on scroll up. |
extended | extended | boolean | false | Show the action label next to its icon. |
href | href | string | undefined | – | A nonempty destination renders an anchor. Relative URLs and fragments retain native resolution. |
icon-name | iconName | string | undefined | – | Registered Lucide name. Import the icon module before rendering. The icon slot takes precedence. |
label | label | string | – | Accessible name of the action. Also the visible text in the extended state. |
position | position | "fixed" | "static" | 'static' | Fixed sits at the viewport's block-end inline-end corner. Reserve page clearance there. |
size | size | "lg" | "md" | "xl" | 'md' | Square footprint when icon-only, and minimum size when extended. |
variant | variant | "primary" | "secondary" | "surface" | 'secondary' | Surface and ink: strong primary, tinted secondary or raised surface. |
Events
| Event | Detail type | Description |
|---|---|---|
click | Event | Native activation click. The page or guarded renderer handles the declared action. |
Slots
| Slot | Description |
|---|---|
icon | Decorative, noninteractive icon replacing the named glyph. |
CSS parts
| Part | Description |
|---|---|
control | The native button or link, including its surface and focus ring. |
icon | Wrapper for the decorative named or slotted glyph. |
label | Visible label of an extended FAB. |
CSS custom properties
The public styling contract of ki-fab: 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-collapse-duration | Duration of the extended FAB footprint change. |
--ki-fab-collapse-easing | Easing of the extended FAB footprint change. |
--ki-fab-fg | Ink on the tinted secondary FAB. |
--ki-fab-font-family | Typeface for FAB labels. |
--ki-fab-font-size | Text size for extended FAB labels. |
--ki-fab-font-weight | Text weight for extended FAB labels. |
--ki-fab-forced-colors-border-width | Boundary width for the FAB in forced colors. |
--ki-fab-gap | Space between icon and label in an extended FAB. |
--ki-fab-hover-shadow | FAB elevation for a pointer that can hover. |
--ki-fab-icon-size | Glyph size of the default FAB. |
--ki-fab-lg-icon-size | Glyph size of the medium FAB. |
--ki-fab-lg-radius | Corner radius of the medium FAB. |
--ki-fab-lg-size | Minimum footprint of the medium FAB. |
--ki-fab-line-height | Line height for extended FAB labels. |
--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-padding-inline-end | Inline end padding of an extended FAB. |
--ki-fab-padding-inline-start | Inline start padding of an extended FAB. |
--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-fab-xl-icon-size | Glyph size of the large FAB. |
--ki-fab-xl-radius | Corner radius of the large FAB. |
--ki-fab-xl-size | Minimum footprint of the large 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. |