Pivot Docs

    Button Open in Figma

    Buttons are essential components in user interfaces, acting as gateways for interaction. They come in various styles, each serving a distinct purpose. Consistency in hierarchy helps guide users through their journey, ensuring that they can easily identify the most important actions to take.

    pivot-button is a flexible action component that renders either a <button> or an <a> element depending on whether pivot-href is set. It supports three visual variants (primary, secondary, tertiary), an inverse color scheme for use on dark backgrounds, a destructive modifier for dangerous actions, and a disabled state.


    Quick Start

    <!-- Default primary button -->
    <pivot-button>Submit</pivot-button>

    <!-- Secondary button -->
    <pivot-button pivot-variant="secondary">Cancel</pivot-button>

    <!-- Tertiary button with destructive styling -->
    <pivot-button pivot-variant="tertiary" pivot-destructive>Delete</pivot-button>

    <!-- Link button (renders as <a>) -->
    <pivot-button pivot-href="/dashboard">Go to Dashboard</pivot-button>

    <!-- Disabled button -->
    <pivot-button pivot-disabled>Unavailable</pivot-button>

    Rendering Behavior

    pivot-button switches its inner element based on context:

    • No pivot-href → renders a <button> element. Use for actions (submit, open dialog, trigger function).
    • With pivot-href → renders an <a> element. Use for navigation.
    <!-- Renders <button type="button"> -->
    <pivot-button pivot-variant="primary">Save</pivot-button>

    <!-- Renders <a href="/profile"> -->
    <pivot-button pivot-variant="primary" pivot-href="/profile"
    >
    View Profile</pivot-button
    >


    <!-- Form submit button -->
    <pivot-button pivot-type="submit">Submit Form</pivot-button>

    Choosing the correct form matters for semantics: <button> triggers actions; <a> navigates. Do not use pivot-href when the intent is an action.

    Note: pivot-disabled sets the disabled attribute on the inner <button> only. It has no effect when pivot-href is set, because disabled is not a valid attribute on <a> elements — see Disabled State below.


    Variant and Modifier Combinations

    Variants and modifiers can be combined freely:

    <!-- Inverse — for dark backgrounds -->
    <pivot-button pivot-variant="primary" pivot-inverse
    >
    Primary Inverse</pivot-button
    >

    <pivot-button pivot-variant="secondary" pivot-inverse
    >
    Secondary Inverse</pivot-button
    >


    <!-- Destructive -->
    <pivot-button pivot-variant="primary" pivot-destructive
    >
    Delete Account</pivot-button
    >

    <pivot-button pivot-variant="secondary" pivot-destructive>Remove</pivot-button>

    <!-- Inverse + Destructive -->
    <pivot-button pivot-variant="primary" pivot-inverse pivot-destructive
    >
    Delete (dark bg)</pivot-button
    >

    With Icons

    Place icon elements directly inside the default slot. Icons are styled automatically to match button token sizes (--typography-constants-icon-family, --typography-icon-sm-size).

    <!-- Leading icon -->
    <pivot-button pivot-variant="primary">
    <i class="fa-solid fa-plus"></i> Add Item
    </pivot-button>

    <!-- Trailing icon -->
    <pivot-button pivot-variant="secondary">
    Download <i class="fa-solid fa-arrow-down"></i>
    </pivot-button>

    Icons slotted into pivot-button are decorative when accompanied by visible label text and should be hidden from assistive technology:

    <pivot-button pivot-variant="primary">
    <i class="fa-solid fa-check" aria-hidden="true"></i> Confirm
    </pivot-button>

    If the button has no visible text label (icon-only), provide an accessible name via aria-label on the host element:

    <pivot-button pivot-variant="tertiary" aria-label="Close dialog">
    <i class="fa-solid fa-xmark"></i>
    </pivot-button>

    Form Participation

    pivot-button is a form-associated custom element (static formAssociated = true plus attachInternals()), which gives it access to the ancestor <form> via ElementInternals.form — even though the native <button> it renders lives inside its own shadow root, not inside the <form> itself.

    • pivot-type="submit" submits that ancestor form when clicked, via a temporary submitter proxy (see below). This runs the browser’s native constraint validation (unless the form has pivot-no-validate set) before submitting — see Form Container’s Validation Behavior.
    • pivot-type="reset" calls form.reset(), restoring every form-associated control inside the form to its initial value.
    • pivot-type="button" and pivot-type="menu" do nothing form-related — only the element’s own native click event fires.
    • If there is no ancestor <form> (a pivot-button used outside any form), pivot-type="submit"/"reset" are no-ops.
    <pivot-form-container pivot-action="/submit">
    <pivot-input pivot-name="email" pivot-label="Email"></pivot-input>
    <pivot-button pivot-type="submit">Submit</pivot-button>
    <pivot-button pivot-variant="secondary" pivot-type="reset"
    >
    Reset</pivot-button
    >

    </pivot-form-container>

    Disabled state and an ancestor <fieldset>

    Because pivot-button is form-associated, formDisabledCallback runs automatically when an ancestor <fieldset disabled> (or a disabled form) contains it, setting pivotDisabled to match — mirroring native <button> behavior. This is in addition to setting pivot-disabled directly.

    How pivot-name/pivot-value reach the submitted form

    A form-associated custom element like pivot-button cannot itself be passed to requestSubmit() as a submitter — per the HTML spec, only a native <button type="submit">/<input type="submit"|"image"> qualifies, and passing an arbitrary custom element throws a TypeError. The real native <button> pivot-button renders isn’t eligible either, since it lives inside pivot-button’s own shadow root and is never a descendant of the outer <form>.

    To work around this, handleClick() builds a temporary, hidden native <button type="submit">, copies pivot-name/pivot-value onto it, and inserts it as a light-DOM sibling immediately after pivot-button itself — making it a genuine descendant of the form and a valid submitter. It’s passed to form.requestSubmit(proxy) and removed immediately afterward; validation, the submit event, and any pivot-method="dialog" side effects all happen synchronously within that call, so nothing depends on the proxy still being in the DOM once it returns. This proxy is purely internal plumbing — it’s never visible, never independently focusable, and the element the user actually sees and interacts with remains pivot-button’s own shadow-DOM <button>.

    The practical effect: pivot-name/pivot-value are included in the submitted FormData exactly as they would be for a native <button type="submit" name="…" value="…">, and for pivot-method="dialog" forms, dialog.returnValue correctly reflects the pivot-value of whichever button was clicked — see Form Container’s pivot-method="dialog" example.

    Because the proxy is inserted at pivot-button’s own position rather than appended to the end of the form, relative DOM order between multiple submit buttons is preserved — this is also what the browser uses to pick the form’s implicit “default button” when a user presses Enter in a text field, so behavior matches a native form with multiple submit buttons.


    Accessibility

    Screen Reader Behavior

    pivot-button does not add an ARIA role of its own — the accessible role comes entirely from the inner element it renders. With no pivot-href, the inner <button> is announced as a button; with pivot-href set, the inner <a> is announced as a link. Use <pivot-button> (no pivot-href) for actions and <pivot-button pivot-href="..."> for navigation — this distinction is critical, since using the wrong element misleads screen reader users about what will happen when they activate it (WCAG 2.2 4.1.2 Name, Role, Value).

    Disabled State

    pivot-disabled sets the disabled attribute on the inner <button>, which removes it from the tab order and prevents activation; screen readers announce it as “dimmed” or “unavailable”. pivot-disabled has no semantic effect when combined with pivot-href, because disabled is not a valid attribute on <a> elements — the link remains focusable and clickable. To disable a link button, avoid pivot-href and handle navigation conditionally in application code, or omit the link entirely.

    pivotDisabled can also be set indirectly, not just via the pivot-disabled attribute — see Form Participation’s Disabled state for how an ancestor disabled <fieldset> triggers the same state automatically.

    Keyboard Navigation

    Key Behavior
    Tab Moves focus to the button
    Enter Activates both <button> and <a> elements
    Space Activates <button> elements only

    This matches native <button>/<a> behavior; pivot-button adds no custom key handling of its own (WCAG 2.2 2.1.1 Keyboard).

    Focus Management

    PivotBase sets delegatesFocus: true on the shadow root, so the inner <button> or <a> receives focus directly — there is no wrapper element in the focus path, and no .focus()/.blur() methods are exposed on the component itself. The native :focus outline is preserved (outline-offset: 4px), keeping focus visible per WCAG 2.2 2.4.7 Focus Visible.


    References


    API Reference

    Props

    Name Type Default Description
    pivot-variant "primary" | "secondary" | "tertiary" "primary" The button variant style. Allowed values: "primary", "secondary", "tertiary".
    pivot-href string "" This will create an attribute: href="value"
    pivot-target "_blank" | "_self" | "_parent" | "_top" | string | null null This will create an attribute: target="value"
    pivot-name string | null null This will create an attribute: name="value"
    pivot-value string | null null This will create an attribute: value="value"
    pivot-type "button" | "submit" | "reset" | "menu" | null null The button type attribute. Allowed values: "button", "submit", "reset", "menu".
    pivot-disabled boolean false Presence of attribute means true: <pivot-button pivot-disabled>
    pivot-inverse boolean false Button inverse styling. Presence of attribute means true: <pivot-button pivot-inverse>
    pivot-destructive boolean false Button destructive styling. Presence of attribute means true: <pivot-button pivot-destructive>

    Slots

    Name Description
    default Default slot for the button label and optional icon(s)

    CSS Custom Properties

    Name Description
    --component-button-gap Gap between icon and label content.
    --component-button-constants-inset-y Vertical padding of the button.
    --component-button-constants-inset-x Horizontal padding of the button.
    --typography-private-interactive-family Font family used for the button label.
    --typography-private-interactive-button-size Font size used for the button label.
    --button-border-style Border style of the button. Default: solid.
    --component-button-constants-border Border width of the button.
    --component-button-constants-radius Border radius of the button.
    --typography-constants-icon-family Font family applied to slotted `<i>`/`<svg>` icons.
    --typography-icon-sm-size Font size applied to slotted `<i>`/`<svg>` icons.
    --component-button-primary-default-surface Background and border color for the primary variant.
    --component-button-primary-default-label Text color for the primary variant.
    --component-button-primary-default-destructive-surface Background and border color for the primary variant with `pivot-destructive`.
    --component-button-primary-default-destructive-label Text color for the primary variant with `pivot-destructive`.
    --component-button-primary-inverse-default-surface Background and border color for the primary variant with `pivot-inverse`.
    --component-button-primary-inverse-default-label Text color for the primary variant with `pivot-inverse`.
    --component-button-primary-inverse-default-destructive-surface Background and border color for the primary variant with `pivot-inverse` and `pivot-destructive`.
    --component-button-primary-inverse-default-destructive-label Text color for the primary variant with `pivot-inverse` and `pivot-destructive`.
    --component-button-secondary-default-surface Background color for the secondary variant.
    --component-button-secondary-default-label Text color for the secondary variant.
    --component-button-secondary-default-border-color Border color for the secondary variant.
    --component-button-secondary-default-destructive-surface Background color for the secondary variant with `pivot-destructive`.
    --component-button-secondary-default-destructive-label Text color for the secondary variant with `pivot-destructive`.
    --component-button-secondary-default-destructive-border-color Border color for the secondary variant with `pivot-destructive`.
    --component-button-color Hover, focus, and active mix color for the secondary and tertiary variants.
    --component-button-secondary-inverse-default-surface Background color for the secondary variant with `pivot-inverse`.
    --component-button-secondary-inverse-default-label Text color for the secondary variant with `pivot-inverse`.
    --component-button-secondary-inverse-default-border-color Border color for the secondary variant with `pivot-inverse` (also used when `pivot-destructive` is combined with `pivot-inverse`).
    --component-button-secondary-inverse-default-destructive-label Text color for the secondary variant with `pivot-inverse` and `pivot-destructive`.
    --component-button-secondary-inverse-default-destructive-border-color Border color for the secondary variant with `pivot-inverse` and `pivot-destructive`.
    --component-button-tertiary-default-surface Background color for the tertiary variant (also used with `pivot-destructive`).
    --component-button-tertiary-default-label Text color for the tertiary variant.
    --component-button-tertiary-default-destructive-label Text color for the tertiary variant with `pivot-destructive`.
    --component-button-tertiary-inverse-default-surface Background color for the tertiary variant with `pivot-inverse` (also used with `pivot-destructive` combined).
    --component-button-tertiary-inverse-default-label Text color for the tertiary variant with `pivot-inverse`.
    --component-button-tertiary-inverse-default-destructive-label Text color for the tertiary variant with `pivot-inverse` and `pivot-destructive`.
    --component-button-tertiary-disabled-label Text color when `pivot-disabled` is set.
    --component-button-tertiary-disabled-surface Background color when `pivot-disabled` is set.
    --component-button-primary-inverse-disabled-label Text color when `pivot-disabled` and `pivot-inverse` are both set.
    --component-button-primary-inverse-disabled-surface Background color when `pivot-disabled` and `pivot-inverse` are both set.