Icon Button
pivot-icon-button is an icon-only button. It renders a <button> by default, or an <a> when pivot-href is set. It displays a single <i> or <svg> icon, hides any other slotted content, and supports four color variants (default, primary, inverse, destructive).
Quick Start
<!-- Default -->
<pivot-icon-button pivot-label="Edit profile">
<i class="fa-solid fa-pencil" aria-hidden="true"></i>
</pivot-icon-button>
<!-- Primary -->
<pivot-icon-button pivot-variant="primary" pivot-label="Add item">
<i class="fa-solid fa-plus" aria-hidden="true"></i>
</pivot-icon-button>
<!-- Inverse, for dark backgrounds -->
<pivot-icon-button pivot-variant="inverse" pivot-label="Close">
<i class="fa-solid fa-xmark" aria-hidden="true"></i>
</pivot-icon-button>
<!-- Link (renders <a>) -->
<pivot-icon-button pivot-label="Home" pivot-href="#">
<i class="fa-solid fa-house" aria-hidden="true"></i>
</pivot-icon-button>Rendering Behavior
pivot-icon-button switches its inner element based on pivot-href:
- No
pivot-href→ renders a<button type="button">. Use for actions (open a dialog, close a panel, toggle a menu). - With
pivot-href→ renders an<a>. Use for navigation.
Don’t set pivot-href when the intent is an action; screen readers announce links and buttons differently.
pivot-target is passed through to the anchor’s target attribute and only applies when pivot-href is set:
<pivot-icon-button
pivot-label="Open documentation in a new tab"
pivot-href="#"
pivot-target="_blank"
>
<i class="fa-solid fa-arrow-up-right-from-square" aria-hidden="true"></i>
</pivot-icon-button>Icon Content
The default slot only renders <i> and <svg> elements. Any other element or text placed in the slot is hidden.
<!-- Font Awesome icon -->
<pivot-icon-button pivot-label="Search">
<i class="fa-solid fa-magnifying-glass" aria-hidden="true"></i>
</pivot-icon-button>
<!-- Inline SVG; sized to the icon font size and filled with the current color -->
<pivot-icon-button pivot-label="Menu">
<svg viewBox="0 0 24 24" aria-hidden="true">
<path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"></path>
</svg>
</pivot-icon-button>Icons are decorative because the accessible name comes from pivot-label, so mark them with aria-hidden="true".
Accessibility
Screen Reader Behavior
The component adds no ARIA role of its own. The inner <button> is announced as a button and the inner <a> as a link, per WCAG 2.2 4.1.2 Name, Role, Value.
Accessible Name
There is no visible text, so pivot-label is required. It is applied as aria-label on the inner <button> or <a>. Describe the action or destination, not the icon (for example, “Edit profile” rather than “Pencil”), per WCAG 2.2 2.4.4 Link Purpose (In Context).
When using pivot-target="_blank", mention it in the label (for example, “Open documentation in a new tab”) so users aren’t surprised by the new window.
Keyboard Navigation
| Key | Behavior |
|---|---|
Tab |
Moves focus to the button or link |
Enter |
Activates both <button> and <a> elements |
Space |
Activates <button> elements only |
This matches native <button>/<a> behavior; the component adds no custom key handling.
Focus Management
PivotBase sets delegatesFocus: true on the shadow root, so the inner <button> or <a> receives focus directly. The native focus outline is preserved (outline-offset: 2px), per WCAG 2.2 2.4.7 Focus Visible.
Target Size
The button is 44 × 44 px by default (--global-interaction-md), meeting WCAG 2.2 2.5.8 Target Size (Minimum).
Color Contrast
Use pivot-variant="inverse" on dark backgrounds so the icon keeps sufficient contrast, per WCAG 2.2 1.4.11 Non-text Contrast.
References
- MDN —
<button>: The Button element - MDN —
<a>: The Anchor element - ARIA Authoring Practices Guide — Button Pattern
- ARIA Authoring Practices Guide — Link Pattern
- WCAG 2.2 — Link Purpose (In Context) (2.4.4)
- WCAG 2.2 — Name, Role, Value (4.1.2)
- WCAG 2.2 — Focus Visible (2.4.7)
- WCAG 2.2 — Target Size (Minimum) (2.5.8)
API Reference
Props
| Name | Type | Default | Description |
|---|---|---|---|
pivot-label |
string |
"" |
Accessible name for the button. Required since it has no visible text. |
pivot-variant |
"default" | "primary" | "inverse" | "destructive" |
"default" |
The button variant style. Allowed values: "default", "primary", "inverse", "destructive". |
pivot-href |
string |
"" |
Optional link destination. When set, renders an `<a>` instead of a `<button>`. |
pivot-target |
"_blank" | "_self" | "_parent" | "_top" | string | null |
null |
The anchor's target attribute. Only applies when `pivot-href` is set. |
Slots
| Name | Description |
|---|---|
default |
Icon slot. Accepts a single `<i>` or `<svg>` element. |
CSS Custom Properties
| Name | Description |
|---|---|
--global-interaction-md |
Width and height of the button. Default: 44px. |
--typography-icon-lg-size-brand |
Font size of the slotted icon. Default: 24px. |
--typography-constants-icon-brand-family |
Font family applied to slotted `<i>`/`<svg>` icons. Default: "Font Awesome 7 Brands". |
--global-color-icons-font-awesome-default-color |
Icon color for the default variant. |
--global-color-icons-font-awesome-primary-color |
Icon color for the primary variant. |
--global-color-icons-font-awesome-inverse-color |
Icon color for the inverse variant. |
--global-color-icons-font-awesome-danger-color |
Icon color for the destructive variant. |
Variants — light surface with primary color value
<pivot-icon-button pivot-label="Edit">
<i class="fa-solid fa-pencil" aria-hidden="true"></i>
</pivot-icon-button>
<pivot-icon-button pivot-variant="primary" pivot-label="Add item">
<i class="fa-solid fa-plus" aria-hidden="true"></i>
</pivot-icon-button>Inverse — dark surface
<pivot-icon-button pivot-variant="inverse" pivot-label="Close">
<i class="fa-solid fa-xmark" aria-hidden="true"></i>
</pivot-icon-button>Destructive
<pivot-icon-button pivot-variant="destructive" pivot-label="Delete item">
<i class="fa-solid fa-trash" aria-hidden="true"></i>
</pivot-icon-button>SVG icon
<pivot-icon-button pivot-label="Menu">
<svg viewBox="0 0 24 24" aria-hidden="true">
<path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"></path>
</svg>
</pivot-icon-button>Link rendering (pivot-href)
Setting pivot-href renders an <a> instead of a <button>. Use it for navigation, not actions. pivot-target only applies in this mode.
<pivot-icon-button pivot-label="Home" pivot-href="#">
<i class="fa-solid fa-house" aria-hidden="true"></i>
</pivot-icon-button>
<pivot-icon-button
pivot-variant="primary"
pivot-label="Open in new tab"
pivot-href="#"
pivot-target="_blank"
>
<i class="fa-solid fa-arrow-up-right-from-square" aria-hidden="true"></i>
</pivot-icon-button>Non-icon content is ignored
Only <i> and <svg> elements are rendered. Text or other elements placed in the slot are hidden.
<pivot-icon-button pivot-label="Delete">
<i class="fa-solid fa-trash" aria-hidden="true"></i> Delete
<span>ignored</span>
</pivot-icon-button>