Pivot Docs

    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


    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.