Pivot Docs

    Chip

    pivot-chip is a compact, dismissible label used to display a discrete value with a remove control. It is designed to represent a single entry within a collection of user-supplied values.

    This component must only be used inside a supported form component. It is not a standalone component and should never be placed independently in markup. See Supported Form Components.


    Quick Start

    pivot-chip is rendered internally — you do not author it directly. Enable chip rendering on a supported host component instead:

    <pivot-input
    pivot-name="guests"
    pivot-label="Guest name"
    pivot-chip
    >
    </pivot-input>

    Pressing Enter with a nonblank value in the field above creates a removable pivot-chip below the field and clears the input for the next entry.


    Overview

    The component renders the chip’s label text alongside a remove button. Activating the remove button dispatches a pivot-chip-remove event that the host component listens for to remove the corresponding value from its internal state.

    pivot-chip has no knowledge of the values around it — the host component (e.g. pivot-input) owns the list of values, renders one pivot-chip per entry, and handles removal.

    The chip is not form-associated itself. Its host component owns ElementInternals and submits each chip label as a separate form value under the host’s pivot-name.

    The label property is declared with attribute: false, so it has no corresponding HTML attribute — a host component must assign it as a JS property (.label = value), not label="value" in markup.


    Using the pivot-chip-remove event

    pivot-chip never removes itself from the DOM. Activating the remove button only dispatches pivot-chip-remove — a bubbling, composed CustomEvent with no detail payload. The surrounding host is responsible for listening for the event and updating its own state so the chip is no longer rendered on the next render pass.

    <div id="chip-bag">
    <pivot-chip data-chip-index="0"></pivot-chip>
    <pivot-chip data-chip-index="1"></pivot-chip>
    </div>
    const chipBag = document.getElementById("chip-bag");

    chipBag.addEventListener("pivot-chip-remove", (event) => {
    // event.detail is undefined — pivot-chip carries no payload of its own.
    // Use event.currentTarget/event.target (or a data attribute you set when
    // rendering the chip) to identify which chip fired the event, then remove
    // it from your own data and re-render — pivot-chip will not do this for you.
    const chip = event.currentTarget;
    const index = Number(chip.dataset.chipIndex);
    removeValueAt(index); // your own state update
    });

    This is exactly the pattern pivot-input uses internally: it renders one pivot-chip per entry in an array with a data-chip-index attribute and a listener bound per-instance, and on pivot-chip-remove it filters that index out of its own chipValues array, letting Lit’s re-render drop the corresponding pivot-chip from the DOM.

    Because the event is dispatched with composed: true, a listener anywhere above the chip’s shadow root — the host component itself, or an ancestor further up the light DOM — will receive it, so you are not required to attach the listener directly on the <pivot-chip> element.


    Supported Form Components

    pivot-chip is only supported as an internally rendered child of the following components:

    Component Enabling attribute
    pivot-input pivot-chip

    Additional form components may add support for chip rendering in the future.


    When to Use

    pivot-chip is not selected directly — it is rendered automatically when a supported host component’s chip mode is enabled. Enable chip mode when:

    • A field collects multiple discrete, freeform values (e.g. guest names, tags, email addresses).
    • Users benefit from seeing and individually removing each previously entered value.

    When Not to Use

    • Do not use this component outside of a supported form component. It is not designed to be authored standalone in markup.
    • Do not use for a single value. If the field only ever holds one value, a plain pivot-input without pivot-chip is sufficient.
    • Do not use for long-form or multi-line content. Chips are meant for short, scannable labels, not sentences or paragraphs.

    Implementation Notes

    • The host component (e.g. pivot-input) is responsible for creating chip values, rendering one pivot-chip per value, and removing values from its own state when notified.
    • The host component submits each chip as a separate FormData entry under its pivot-name; pivot-chip does not call attachInternals() or submit independently.
    • pivot-chip dispatches pivot-chip-remove (bubbling, composed) when its remove button is activated. It does not remove itself — the host component must handle the event and update its value list (see Using the pivot-chip-remove event).
    • The remove button renders an inline SVG “X” icon and derives its accessible name from the chip’s label (aria-label="Remove {label}").

    Content Guidelines

    • Keep chip labels short. Chips are meant to be scannable at a glance — avoid long phrases or sentences.
    • Use consistent casing and formatting across chips rendered within the same field for a cohesive appearance.

    CSS Parts

    Part Element
    container The chip container.
    remove The chip’s remove button.

    Accessibility

    pivot-chip renders no ARIA role of its own — a <span part="container"> holds the label text as plain text content, followed by a native <button part="remove">. The button’s accessible name is generated per-instance from the chip’s label (aria-label="Remove {label}"), so assistive technology hears a specific action (e.g. “Remove Jane Doe”) rather than a generic, ambiguous “Remove” button — satisfying WCAG 4.1.2 (Name, Role, Value).

    Screen Reader Behavior

    A screen reader encounters each chip’s label as static text, immediately followed by a button named “Remove {label}”. pivot-chip does not group the label and button under a shared role (e.g. group or listitem), and when several chips are rendered as siblings it provides no list/group semantics tying them together as a set — any such grouping is the host’s responsibility. pivot-input, for example, wraps its rendered chips in a <div class="chip-bag" aria-label="Selected values">; a host that omits an equivalent wrapper leaves screen reader users without a way to tell how many chips exist or where the set begins and ends.

    Keyboard Navigation

    Key Behavior
    Tab / Shift+Tab Moves focus to (or away from) the chip’s remove button, in document order.
    Space / Enter Activates the remove button (native <button> semantics), dispatching pivot-chip-remove.

    All keyboard behavior comes from the native <button> element — pivot-chip attaches no keyboard handlers of its own, so operability follows standard button semantics (WCAG 2.1.1).

    Focus Management

    pivot-chip inherits shadowRootOptions: { delegatesFocus: true } from PivotBase. This means calling .focus() on the <pivot-chip> host element delegates focus into its shadow DOM, landing on the remove button (its only focusable element).

    When a host component removes a chip in response to pivot-chip-remove, it should restore focus explicitly. The supported pivot-input host moves focus to the next remaining chip’s remove button, or the previous chip when the last chip was removed; when no chips remain, it returns focus to the originating text field. Other hosts should provide equivalent focus management for their own chip collections.


    Related Components

    • Input — the only currently supported host component; renders pivot-chip instances from its chipValues state, sets each chip’s label via JS property binding, and owns pivot-chip-remove handling and form submission.

    References


    API Reference

    Events

    Name Type Description
    pivot-chip-remove CustomEvent Fired when the chip's remove button is activated.

    CSS Custom Properties

    Name Description
    --component-chip-default-surface-default Chip background color.
    --component-chip-default-label-default Chip text color.
    --component-chip-gap Gap between the chip label and remove button.
    --component-chip-inset-y Vertical (block) padding inside the chip.
    --component-chip-inset-left Padding between the chip's leading edge and its label.
    --component-chip-inset-right Padding between the chip's label/remove button and its trailing edge.
    --component-chip-border-color Chip border color.
    --component-chip-border Chip border width.
    --component-chip-radius Chip border radius.