# FloatingActionButton

A circular frosted-glass action button that floats over screen content in the bottom-right corner.

Version: 0.2.0-preview.1 (preview)
Content digest: 70ac710f4d22dce040e7ac593379ba8aca9dcb59a0b9c0f839819cae0e2bb721
Contract kind: source-derived
Source: packages/design-system/src/components/primitives/FloatingActionButton/FloatingActionButton.tsx

## Guidance

{
  "summary": "A circular frosted-glass action button that floats over screen content in the bottom-right corner.",
  "guidance": [
    {
      "heading": "Overview",
      "body": "A frosted-glass circle that floats over screen content in the bottom-right corner,\nholding the screen's single primary creation action. The web counterpart of the iOS\n`FloatingActionButton` (glass on iOS 26; this component approximates that look with a\ntranslucent fill and backdrop blur)."
    },
    {
      "heading": "Anchoring",
      "body": "The button anchors itself: `position: fixed`, inset `--cds-space-16` from the right and\nbottom edges plus `env(safe-area-inset-bottom)`. It is deliberately **not** portaled —\ninside a transformed screen container (a Stackflow activity) the transform becomes its\ncontaining block, so it rides push/pop transitions with the screen, exactly like the iOS\n`safeAreaInset` placement. On screens that sit above a tab bar, lift `bottom` with the\n`className` hook."
    },
    {
      "heading": "States",
      "body": "`loading` swaps the glyph for a Spinner and blocks presses. `hidden` scales and fades the\nbutton out, then unmounts it — use it while a sheet covers the screen or the action is\ntemporarily unavailable."
    }
  ],
  "usage": [
    {
      "variant": "FloatingActionButton",
      "use": "The one always-available creation action on a scrolling screen — compose, add, new item.",
      "avoid": "Footer CTAs of a linear flow (use a full-width primary Button); more than one per screen; actions that need a visible label."
    }
  ],
  "examples": [],
  "source": "packages/design-system/src/components/primitives/FloatingActionButton/FloatingActionButton.mdx",
  "status": "local-preview",
  "note": "Guidance is read from local documentation, originally imported from the frozen source. Platform assertions in guidance are not parity verification."
}

## Contract and public API

```json
{
  "props": [
    {
      "name": "icon",
      "type": "React.ReactNode",
      "declared_type": "React.ReactNode",
      "required": true,
      "description": "Glyph rendered in the circle, usually an `Icon`.",
      "source": {
        "path": "packages/design-system/src/components/primitives/FloatingActionButton/FloatingActionButton.tsx",
        "line": 14
      }
    },
    {
      "name": "ariaLabel",
      "type": "string",
      "declared_type": "string",
      "required": true,
      "description": "Accessible name for the action.",
      "source": {
        "path": "packages/design-system/src/components/primitives/FloatingActionButton/FloatingActionButton.tsx",
        "line": 16
      }
    },
    {
      "name": "onPress",
      "type": "(() => void) | undefined",
      "declared_type": "() => void",
      "required": false,
      "description": "Fires on tap. Omitted, the button renders inert without looking disabled.",
      "source": {
        "path": "packages/design-system/src/components/primitives/FloatingActionButton/FloatingActionButton.tsx",
        "line": 18
      }
    },
    {
      "name": "loading",
      "type": "boolean | undefined",
      "declared_type": "boolean",
      "required": false,
      "description": "Swaps the icon for a Spinner and prevents interaction.",
      "source": {
        "path": "packages/design-system/src/components/primitives/FloatingActionButton/FloatingActionButton.tsx",
        "line": 20
      },
      "values": [
        false,
        true
      ],
      "values_complete": true
    },
    {
      "name": "hidden",
      "type": "boolean | undefined",
      "declared_type": "boolean",
      "required": false,
      "description": "Animates the button out and unmounts it, e.g. while a sheet is open.",
      "source": {
        "path": "packages/design-system/src/components/primitives/FloatingActionButton/FloatingActionButton.tsx",
        "line": 22
      },
      "values": [
        false,
        true
      ],
      "values_complete": true
    },
    {
      "name": "haptic",
      "type": "HapticFeedback | undefined",
      "declared_type": "HapticFeedback",
      "required": false,
      "description": "Haptic feedback for successful presses. Defaults to `true` (`light`).",
      "source": {
        "path": "packages/design-system/src/components/primitives/FloatingActionButton/FloatingActionButton.tsx",
        "line": 24
      },
      "values": [
        "error",
        "heavy",
        "light",
        "medium",
        "selection",
        "success",
        "warning",
        false,
        true
      ],
      "values_complete": true,
      "default": "true",
      "default_kind": "source-expression"
    },
    {
      "name": "className",
      "type": "string | undefined",
      "declared_type": "string",
      "required": false,
      "description": "Class hook for composite styling, e.g. lifting `bottom` above a tab bar.",
      "source": {
        "path": "packages/design-system/src/components/primitives/FloatingActionButton/FloatingActionButton.tsx",
        "line": 26
      }
    },
    {
      "name": "style",
      "type": "React.CSSProperties | undefined",
      "declared_type": "React.CSSProperties",
      "required": false,
      "description": "",
      "source": {
        "path": "packages/design-system/src/components/primitives/FloatingActionButton/FloatingActionButton.tsx",
        "line": 27
      }
    },
    {
      "name": "testId",
      "type": "string | undefined",
      "declared_type": "string",
      "required": false,
      "description": "Selector on the `<button>`. Gone from the DOM once a `hidden` exit finishes, not just invisible.",
      "source": {
        "path": "packages/design-system/src/components/primitives/FloatingActionButton/FloatingActionButton.tsx",
        "line": 29
      }
    }
  ],
  "prop_shapes": {},
  "api": {
    "method": "typescript-type-checker",
    "typescript_version": "5.9.3",
    "public_export": "FloatingActionButton",
    "public_path": "FloatingActionButton",
    "import_path": "@cloakedinc/design-system",
    "root_kind": "component",
    "entrypoints": [
      {
        "name": "FloatingActionButton",
        "signature": 1,
        "visibility": "public",
        "source": {
          "path": "packages/design-system/src/components/primitives/FloatingActionButton/FloatingActionButton.tsx",
          "line": 41
        },
        "props_type": "FloatingActionButtonProps",
        "props": [
          {
            "name": "icon",
            "type": "React.ReactNode",
            "declared_type": "React.ReactNode",
            "required": true,
            "description": "Glyph rendered in the circle, usually an `Icon`.",
            "source": {
              "path": "packages/design-system/src/components/primitives/FloatingActionButton/FloatingActionButton.tsx",
              "line": 14
            }
          },
          {
            "name": "ariaLabel",
            "type": "string",
            "declared_type": "string",
            "required": true,
            "description": "Accessible name for the action.",
            "source": {
              "path": "packages/design-system/src/components/primitives/FloatingActionButton/FloatingActionButton.tsx",
              "line": 16
            }
          },
          {
            "name": "onPress",
            "type": "(() => void) | undefined",
            "declared_type": "() => void",
            "required": false,
            "description": "Fires on tap. Omitted, the button renders inert without looking disabled.",
            "source": {
              "path": "packages/design-system/src/components/primitives/FloatingActionButton/FloatingActionButton.tsx",
              "line": 18
            }
          },
          {
            "name": "loading",
            "type": "boolean | undefined",
            "declared_type": "boolean",
            "required": false,
            "description": "Swaps the icon for a Spinner and prevents interaction.",
            "source": {
              "path": "packages/design-system/src/components/primitives/FloatingActionButton/FloatingActionButton.tsx",
              "line": 20
            },
            "values": [
              false,
              true
            ],
            "values_complete": true
          },
          {
            "name": "hidden",
            "type": "boolean | undefined",
            "declared_type": "boolean",
            "required": false,
            "description": "Animates the button out and unmounts it, e.g. while a sheet is open.",
            "source": {
              "path": "packages/design-system/src/components/primitives/FloatingActionButton/FloatingActionButton.tsx",
              "line": 22
            },
            "values": [
              false,
              true
            ],
            "values_complete": true
          },
          {
            "name": "haptic",
            "type": "HapticFeedback | undefined",
            "declared_type": "HapticFeedback",
            "required": false,
            "description": "Haptic feedback for successful presses. Defaults to `true` (`light`).",
            "source": {
              "path": "packages/design-system/src/components/primitives/FloatingActionButton/FloatingActionButton.tsx",
              "line": 24
            },
            "values": [
              "error",
              "heavy",
              "light",
              "medium",
              "selection",
              "success",
              "warning",
              false,
              true
            ],
            "values_complete": true,
            "default": "true",
            "default_kind": "source-expression"
          },
          {
            "name": "className",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "Class hook for composite styling, e.g. lifting `bottom` above a tab bar.",
            "source": {
              "path": "packages/design-system/src/components/primitives/FloatingActionButton/FloatingActionButton.tsx",
              "line": 26
            }
          },
          {
            "name": "style",
            "type": "React.CSSProperties | undefined",
            "declared_type": "React.CSSProperties",
            "required": false,
            "description": "",
            "source": {
              "path": "packages/design-system/src/components/primitives/FloatingActionButton/FloatingActionButton.tsx",
              "line": 27
            }
          },
          {
            "name": "testId",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "Selector on the `<button>`. Gone from the DOM once a `hidden` exit finishes, not just invisible.",
            "source": {
              "path": "packages/design-system/src/components/primitives/FloatingActionButton/FloatingActionButton.tsx",
              "line": 29
            }
          }
        ],
        "branches": [],
        "constraints": [],
        "extraction_status": "extracted"
      }
    ],
    "type_sources": [
      {
        "path": "packages/design-system/src/components/primitives/FloatingActionButton/FloatingActionButton.tsx",
        "line": 12,
        "name": "FloatingActionButtonProps",
        "code": "export interface FloatingActionButtonProps {\n    /** Glyph rendered in the circle, usually an `Icon`. */\n    icon: React.ReactNode;\n    /** Accessible name for the action. */\n    ariaLabel: string;\n    /** Fires on tap. Omitted, the button renders inert without looking disabled. */\n    onPress?: () => void;\n    /** Swaps the icon for a Spinner and prevents interaction. */\n    loading?: boolean;\n    /** Animates the button out and unmounts it, e.g. while a sheet is open. */\n    hidden?: boolean;\n    /** Haptic feedback for successful presses. Defaults to `true` (`light`). */\n    haptic?: HapticFeedback;\n    /** Class hook for composite styling, e.g. lifting `bottom` above a tab bar. */\n    className?: string;\n    style?: React.CSSProperties;\n    /** Selector on the `<button>`. Gone from the DOM once a `hidden` exit finishes, not just invisible. */\n    testId?: string;\n}"
      },
      {
        "path": "packages/design-system/src/tokens/CdsHaptic.ts",
        "line": 6,
        "name": "HapticFeedback",
        "code": "export type HapticFeedback = boolean | HapticType;"
      },
      {
        "path": "packages/design-system/src/tokens/HapticType.ts",
        "line": 2,
        "name": "HapticType",
        "code": "export type HapticType = 'light' | 'medium' | 'heavy' | 'success' | 'warning' | 'error' | 'selection';"
      }
    ],
    "defaults_policy": "Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source."
  },
  "spec": {
    "$schema": "../../../specs/component-spec.schema.json",
    "identity": {
      "name": "FloatingActionButton",
      "status": "preview",
      "version": "1.0.1",
      "summary": "A circular frosted-glass action button that floats over screen content in the bottom-right corner."
    },
    "parts": [
      {
        "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."
      }
    ],
    "allowedDesignChoices": {
      "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",
        "appliesTo": [
          "container"
        ]
      },
      {
        "id": "corner-radius",
        "label": "Corner radius",
        "kind": "exact",
        "token": "--cds-radius-full",
        "value": "full",
        "unit": "none",
        "appliesTo": [
          "container"
        ]
      },
      {
        "id": "edge-inset",
        "label": "Edge inset",
        "kind": "exact",
        "token": "--cds-space-16",
        "value": 16,
        "unit": "px",
        "appliesTo": [
          "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",
        "appliesTo": [
          "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."
      ]
    },
    "typographyAndColor": {
      "typography": [],
      "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."
      }
    ],
    "contentAdaptation": [
      {
        "label": "Icon only",
        "description": "Accepts a single glyph; use a verb-like icon (add, compose) that names the screen's primary creation action."
      }
    ],
    "motionHaptics": {
      "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."
        }
      ]
    },
    "platformDifferences": [
      {
        "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."
      }
    ]
  },
  "platforms": {
    "implemented": [
      "web"
    ],
    "native": "Imported design guidance only; no native implementation or parity verification in this preview.",
    "react": {
      "implementation": "local",
      "status": "preview",
      "parity": "web-reference"
    },
    "vue": {
      "implementation": "absent",
      "parity": "not-verified",
      "status": "reference-only"
    },
    "swift": {
      "implementation": "absent",
      "parity": "not-verified",
      "status": "reference-only"
    },
    "kotlin": {
      "implementation": "absent",
      "parity": "not-verified",
      "status": "reference-only"
    }
  },
  "tokens": [
    {
      "name": "--cds-size-48",
      "light": "48px",
      "dark": "48px"
    },
    {
      "name": "--cds-radius-full",
      "light": "9999px",
      "dark": "9999px"
    },
    {
      "name": "--cds-space-16",
      "light": "16px",
      "dark": "16px"
    },
    {
      "name": "--cds-blur-subtle",
      "light": "16px",
      "dark": "16px"
    },
    {
      "name": "--cds-fab-container",
      "light": "#ffffff99",
      "dark": "#ffffff1a"
    },
    {
      "name": "--cds-text-primary",
      "light": "#141410",
      "dark": "#f3f1ed"
    }
  ],
  "review": {
    "local_status": "not-reviewed",
    "source_approval": null,
    "imported_spec_status": "approved",
    "spec_origin": "imported-adapted",
    "local_spec_source_status": "approved",
    "imported_source_revision": "f96f416e1c3bfbfaffcd155a88b87b18b8bb25f1",
    "note": "Inherited specification status is provenance, not approval of the current local implementation or extracted contract."
  },
  "missing_facts": [
    {
      "code": "human-review-pending",
      "detail": "This local preview has no recorded human design or engineering sign-off."
    },
    {
      "code": "platform-parity-unverified",
      "detail": "Vue, Swift and Kotlin implementations are absent from this package; platform parity has not been verified."
    },
    {
      "code": "figma-mapping-unverified",
      "detail": "No current component-level Figma node and immutable revision have been verified for this contract."
    }
  ]
}
```

## Visual states

- [Playground](/storybook/iframe.html?id=cloaked-design-system-primitives-floatingactionbutton--playground&viewMode=story) | export: Playground | source: packages/design-system/src/components/primitives/FloatingActionButton/FloatingActionButton.stories.tsx

- [Loading](/storybook/iframe.html?id=cloaked-design-system-primitives-floatingactionbutton--loading&viewMode=story) | export: Loading | source: packages/design-system/src/components/primitives/FloatingActionButton/FloatingActionButton.stories.tsx

- [Hidden Toggle](/storybook/iframe.html?id=cloaked-design-system-primitives-floatingactionbutton--hidden-toggle&viewMode=story) | export: HiddenToggle | source: packages/design-system/src/components/primitives/FloatingActionButton/FloatingActionButton.stories.tsx

- [Dark Theme](/storybook/iframe.html?id=cloaked-design-system-primitives-floatingactionbutton--dark-theme&viewMode=story) | export: DarkTheme | source: packages/design-system/src/components/primitives/FloatingActionButton/FloatingActionButton.stories.tsx

Preview pending human sign-off. Source-derived APIs and successful checks do not certify accessibility, native parity or approval.