HyFab

Usage examples on this page are written for Lit / plain HTML (<hy-fab>). The same component ships as HyFab in @whitespaceux/harmony-react (native React 19), with typed wrappers for Angular, Solid, Svelte, and Vue. The API reference below applies to all frameworks.

A floating action button (FAB) for primary or prominent actions.

The FAB is a circular button that floats above the UI, representing the most important or frequent action on a screen. It supports an extended variant that shows both an icon and a text label in a pill shape.

Key Features

• Circular (icon-only) and extended (icon + label) variants
• Three sizes: small (40px), medium (48px), large (56px)
• Two identity variants (brand, neutral) aligned with the design system
• Optional fixed positioning with presets (bottom-right, bottom-left, etc.)
• Link mode when href is provided
• Loading state with spinner
• Fully accessible with keyboard navigation
• SSR compatible

Accessibility Features

• aria-label set from the label property in icon-only mode
• In extended mode, visible label text provides the accessible name
• Full keyboard navigation (Enter, Space)
• Visible focus indicators
• Minimum 40px touch target (44px on touch devices)
• High contrast mode support
• Reduced motion support
• Screen reader loading announcements

Examples

Basic icon-only FAB

<hy-fab icon="favorite-border" label="Add to favorites"></hy-fab>

Extended FAB with label

<hy-fab icon="favorite-border" label="Favorite" extended></hy-fab>

Fixed position FAB

<hy-fab icon="favorite-border" label="Favorite" position="bottom-right"></hy-fab>

Brand variant, large size

<hy-fab icon="search" label="Search" variant="brand" size="large"></hy-fab>

Link mode FAB

<hy-fab icon="home" label="Home" href="/home"></hy-fab>

Loading state

<hy-fab icon="cloud-upload" label="Uploading..." loading></hy-fab>

Click gating: Native click events bubble normally. When disabled or loading, clicks are stopped (stopPropagation + preventDefault) on the host so external

## API

### Properties

| Property | Attribute | Type | Default | Description |
| --- | --- | --- | --- | --- |
| `icon` | `icon` | `string \| undefined` | — | The name of the icon to display. Must match an icon in the configured icon set. |
| `label` | `label` | `string` | `''` | Accessible label for the FAB. **Required.** |
| `variant` | `variant` | `'brand' \| 'neutral'` | `'brand'` | The visual variant of the FAB determining color scheme. - `brand` - Primary brand color for the main action (default) - `neutral` - Subtle, non-semantic styling |
| `emphasis` | `emphasis` | `'solid' \| 'soft' \| 'outlined'` | `'solid'` | Visual chrome weight on top of the role. - `solid` (default) — full role fill, on-color icon - `soft` — role-tinted fill, role-colored icon - `outlined` — transparent fill, role border, role-colored icon |
| `size` | `size` | `'small' \| 'medium' \| 'large'` | `'large'` | The size of the FAB. - `small` - 40px, compact for secondary floating actions - `medium` - 48px, balanced size - `large` - 56px, prominent primary actions (Material Design standard, default) |
| `extended` | `extended` | `boolean` | `false` | Whether to display the extended variant (icon + visible label text). Extended FABs render as a pill shape instead of a circle. |
| `disabled` | `disabled` | `boolean` | `false` | Whether the FAB is disabled. |
| `loading` | `loading` | `boolean` | `false` | Whether the FAB is in a loading state. Shows a spinner and prevents interaction. |
| `loadingText` | `loading-text` | `string` | `'Loading'` | Text announced to screen readers during loading state. Use for internationalization. |
| `href` | `href` | `string \| undefined` | — | URL for link mode. When set, the FAB renders as an anchor element. |
| `target` | `target` | `string \| undefined` | — | Link target. Only used when `href` is set. |
| `rel` | `rel` | `string \| undefined` | — | Link rel attribute. Only used when `href` is set. |
| `position` | `position` | `'bottom-right' \| 'bottom-left' \| 'bottom-center' \| 'top-right' \| 'top-left' \| 'top-center'` | — | Preset fixed position for the FAB. When set, the FAB uses `position: fixed` and is placed at the specified viewport corner or edge. |
| `autofocus` | `autofocus` | `boolean` | `false` | Marks this FAB as the auto-focus target. Read by `hy-dialog` (and other overlay containers) on `show` to choose initial focus. Also focuses on first connect when used outside an overlay, mirroring native HTML `autofocus` but routed through JS so SSR'd HTML doesn't pull focus during hydration. |

### Slots

| Slot | Description |
| --- | --- |
| `icon` | Optional slot to provide a custom icon element instead of using the `icon` property |

### CSS Parts

| Part | Description |
| --- | --- |
| `base` | The FAB's base wrapper element (button or anchor tag) |
| `icon` | The icon container |
| `label` | The visible label text (extended mode only) |

### CSS Custom Properties

| Property | Description |
| --- | --- |
| `--hy-fab-text-transform` | Text transform for FAB label |
| `--hy-fab-shadow` | Box shadow at rest |
| `--hy-fab-shadow-hover` | Box shadow on hover |
| `--hy-fab-font-family` | Font family override for FAB label |
| `--hy-fab-hover-duration` | Transition duration for hover and focus state feedback |
| `--hy-fab-hover-easing` | Transition easing for hover and focus state feedback |
| `--hy-fab-spin-duration` | Loading-spinner rotation duration |
| `--hy-fab-spin-easing` | Loading-spinner rotation easing |

## Methods

### focus()

Sets focus on the FAB.

### blur()

Removes focus from the FAB.