Skip to content
Kimenpre-v1documentation home
Color scheme

ki-fab

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.

Theme for this example
Color scheme for this example
<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

AttributePropertyTypeDefaultDescription
collapse-on-scrollcollapseOnScrollbooleanfalseCompact an extended FAB on viewport scroll down and restore on scroll up.
extendedextendedbooleanfalseShow the action label next to its icon.
hrefhrefstring | undefined–A nonempty destination renders an anchor. Relative URLs and fragments retain native resolution.
icon-nameiconNamestring | undefined–Registered Lucide name. Import the icon module before rendering. The icon slot takes precedence.
labellabelstring–Accessible name of the action. Also the visible text in the extended state.
positionposition"fixed" | "static"'static'Fixed sits at the viewport's block-end inline-end corner. Reserve page clearance there.
sizesize"lg" | "md" | "xl"'md'Square footprint when icon-only, and minimum size when extended.
variantvariant"primary" | "secondary" | "surface"'secondary'Surface and ink: strong primary, tinted secondary or raised surface.

Events

EventDetail typeDescription
clickEventNative activation click. The page or guarded renderer handles the declared action.

Slots

SlotDescription
iconDecorative, noninteractive icon replacing the named glyph.

CSS parts

PartDescription
controlThe native button or link, including its surface and focus ring.
iconWrapper for the decorative named or slotted glyph.
labelVisible 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.

TokenDescription
--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-fab-backdrop-filterComplete optional filter behind the FAB.
--ki-fab-bgTinted secondary FAB fill.
--ki-fab-bg-imageOptional layer painted over the FAB fill.
--ki-fab-collapse-durationDuration of the extended FAB footprint change.
--ki-fab-collapse-easingEasing of the extended FAB footprint change.
--ki-fab-fgInk on the tinted secondary FAB.
--ki-fab-font-familyTypeface for FAB labels.
--ki-fab-font-sizeText size for extended FAB labels.
--ki-fab-font-weightText weight for extended FAB labels.
--ki-fab-forced-colors-border-widthBoundary width for the FAB in forced colors.
--ki-fab-gapSpace between icon and label in an extended FAB.
--ki-fab-hover-shadowFAB elevation for a pointer that can hover.
--ki-fab-icon-sizeGlyph size of the default FAB.
--ki-fab-lg-icon-sizeGlyph size of the medium FAB.
--ki-fab-lg-radiusCorner radius of the medium FAB.
--ki-fab-lg-sizeMinimum footprint of the medium FAB.
--ki-fab-line-heightLine height for extended FAB labels.
--ki-fab-mobile-nav-block-sizeHeight to reserve for mobile navigation, excluding the safe-area inset.
--ki-fab-offsetFixed FAB gap to the viewport edge or mobile navigation.
--ki-fab-padding-inline-endInline end padding of an extended FAB.
--ki-fab-padding-inline-startInline start padding of an extended FAB.
--ki-fab-primary-bgStrong primary FAB fill.
--ki-fab-primary-fgInk on the strong primary FAB.
--ki-fab-radiusCorner radius of the default FAB size.
--ki-fab-shadowResting FAB elevation.
--ki-fab-sizeMinimum FAB footprint in the default size.
--ki-fab-surface-bgRaised surface FAB fill.
--ki-fab-surface-fgInk on the raised surface FAB.
--ki-fab-xl-icon-sizeGlyph size of the large FAB.
--ki-fab-xl-radiusCorner radius of the large FAB.
--ki-fab-xl-sizeMinimum footprint of the large FAB.
--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-offsetGap between a focusable component and its keyboard focus ring.
--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.

Workshop

Open ki-fab in Storybook