FloatingActionButton
A circular frosted-glass action button that floats over screen content in the bottom-right corner.
Implementation previewEvery example. In one place.
Explore every named example, including states, compositions, and theme variants.
Example source
packages/design-system/src/components/primitives/FloatingActionButton/FloatingActionButton.stories.tsxExport PlaygroundImplementation preview Local Storybook build 0.2.0-preview.1. Source specification status does not approve this runtime.
Stories + source JSON ↗Local specification source status: preview. Implementation preview pending sign-off.
A circular frosted-glass action button that floats over screen content in the bottom-right corner.
Implementation API 1 entry point · source-derived preview
Read the actual callable API and preserve its composition constraints. Each union branch is a complete alternative; props marked forbidden cannot be supplied.
import { FloatingActionButton } from '@cloakedinc/design-system';FloatingActionButtonFloatingActionButtonProps
packages/design-system/src/components/primitives/FloatingActionButton/FloatingActionButton.tsx:41
| Prop | Type | Presence | Notes |
|---|---|---|---|
icon | React.ReactNode | Required | Glyph rendered in the circle, usually an `Icon`. |
ariaLabel | string | Required | Accessible name for the action. |
onPress | (() => void) | undefined | Optional | Fires on tap. Omitted, the button renders inert without looking disabled. |
loading | boolean | undefined | Optional | Swaps the icon for a Spinner and prevents interaction. |
hidden | boolean | undefined | Optional | Animates the button out and unmounts it, e.g. while a sheet is open. |
haptic | HapticFeedback | undefined | Optional | Haptic feedback for successful presses. Defaults to `true` (`light`).Source default: true |
className | string | undefined | Optional | Class hook for composite styling, e.g. lifting `bottom` above a tab bar. |
style | React.CSSProperties | undefined | Optional | |
testId | string | undefined | Optional | Selector on the `<button>`. Gone from the DOM once a `hidden` exit finishes, not just invisible. |
Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source.
Overview
A frosted-glass circle that floats over screen content in the bottom-right corner,
holding the screen's single primary creation action. The web counterpart of the iOS
FloatingActionButton (glass on iOS 26; this component approximates that look with a
translucent fill and backdrop blur).
Anchoring
The button anchors itself: position: fixed, inset --cds-space-16 from the right and
bottom edges plus env(safe-area-inset-bottom). It is deliberately not portaled —
inside a transformed screen container (a Stackflow activity) the transform becomes its
containing block, so it rides push/pop transitions with the screen, exactly like the iOS
safeAreaInset placement. On screens that sit above a tab bar, lift bottom with the
className hook.
States
loading swaps the glyph for a Spinner and blocks presses. hidden scales and fades the
button out, then unmounts it — use it while a sheet covers the screen or the action is
temporarily unavailable.
Usage by variant
| Choice | Use when | Avoid when |
|---|---|---|
FloatingActionButton | The one always-available creation action on a scrolling screen — compose, add, new item. | Footer CTAs of a linear flow (use a full-width primary Button); more than one per screen; actions that need a visible label. |
Component specification
$schema
../../../specs/component-spec.schema.jsonParts
- Id
- container
- Label
- Container
- Description
- The fixed-position glass circle that owns the tap target, elevation, and anchoring.
- Id
- icon
- Label
- Icon
- Description
- The sole visible content; every FloatingActionButton is icon-only.
- Id
- loading-indicator
- Label
- Loading indicator
- Description
- Replaces the icon while preserving the circle geometry during loading.
Allowed Design Choices
- Variants
- Default
- Label
- Default
- Description
- Single glass treatment; there is no variant axis.
- Sizes
- Default
- Label
- Default
- Description
- Single fixed 48px diameter; there is no size axis.
Variants
- Id
- default
- Label
- Default
- Description
- Frosted-glass circle with the theme text color for the glyph.
- Platforms
- ios
- web
Sizes
- Id
- default
- Label
- Default
- Description
- Fixed 48px circle matching the iOS component.
Measurements
- Id
- diameter
- Label
- Diameter
- Kind
- exact
- Token
- --cds-size-48
- Value
- 48
- Unit
- px
- Applies To
- container
- Id
- corner-radius
- Label
- Corner radius
- Kind
- exact
- Token
- --cds-radius-full
- Value
- full
- Unit
- none
- Applies To
- container
- Id
- edge-inset
- Label
- Edge inset
- Kind
- exact
- Token
- --cds-space-16
- Value
- 16
- Unit
- px
- Applies To
- container
- Notes
- Right and bottom inset; the bottom additionally clears env(safe-area-inset-bottom).
- Id
- backdrop-blur
- Label
- Backdrop blur
- Kind
- exact
- Token
- --cds-blur-subtle
- Value
- 16
- Unit
- px
- Applies To
- container
Layout
- Alignment
- The icon or Spinner is centered in both axes of the circle.
- Flow
- Self-anchors with position: fixed to the bottom-right of its containing block.
- Notes
- Deliberately not portaled: a transformed screen container (e.g. a Stackflow activity) becomes the containing block, so the button rides screen push/pop transitions like the iOS safeAreaInset placement.
- The default inset clears the device safe area only; screens that sit above a tab bar lift the bottom inset via className.
Typography And Color
- Typography
- None specified
- Colors
- Label
- Container
- Description
- Translucent frosted-glass fill paired with the backdrop blur.
- Token
- --cds-fab-container
- Label
- Icon
- Description
- Theme text color, matching the iOS glass treatment.
- Token
- --cds-text-primary
States
- Id
- active
- Label
- Active
- Description
- Available for press; presses scale the circle to 0.97.
- Id
- loading
- Label
- Loading
- Description
- Blocks presses, hides the icon, and centers a Spinner without changing geometry.
- Id
- hidden
- Label
- Hidden
- Description
- Scales and fades out, then unmounts; re-showing animates back in.
Behavior
- Label
- Press
- Description
- Calls onPress once for a non-loading button.
- Label
- Loading
- Description
- Treats loading as disabled and exposes the busy state to assistive technology.
- Label
- Hide and show
- Description
- The hidden prop drives a scale-and-fade transition before unmount; reduced-motion preferences collapse it to an instant swap.
Accessibility
- Label
- Accessible name
- Description
- ariaLabel is required; the button never renders visible text.
- Label
- Native semantics
- Description
- Renders a native button element and forwards disabled and aria-busy state.
Content Adaptation
- Label
- Icon only
- Description
- Accepts a single glyph; use a verb-like icon (add, compose) that names the screen's primary creation action.
Motion Haptics
- Motion
- Label
- Press feedback
- Description
- Scales to 0.97 over the fast duration, mirroring the iOS press treatment.
- Label
- Hide and show
- Description
- Scale-and-fade over the base duration with the standard enter and exit curves, gated by prefers-reduced-motion.
- Haptics
- Label
- Default feedback
- Description
- Uses a light haptic for successful presses when a native bridge is available.
Platform Differences
- Platforms
- web
- Description
- The glass chrome is a backdrop-filter approximation; iOS 26 uses the native interactive glassEffect and earlier iOS falls back to a solid inverted circle.
- Rationale
- WKWebView content has no liquid-glass API, so the web treatment chases the iOS 26 look with a translucent fill and blur.
- Platforms
- web
- Description
- The menu-opening flavor is the sibling FloatingActionMenuButton component, mirroring the iOS split.
- Rationale
- Menu triggers carry a different interaction and accessibility contract than action buttons, so the flavor is a separate component rather than a prop.