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-inputwithoutpivot-chipis 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 onepivot-chipper value, and removing values from its own state when notified. - The host component submits each chip as a separate
FormDataentry under itspivot-name;pivot-chipdoes not callattachInternals()or submit independently. pivot-chipdispatchespivot-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 thepivot-chip-removeevent).- 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-chipinstances from itschipValuesstate, sets each chip’slabelvia JS property binding, and ownspivot-chip-removehandling 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. |
Chip labels (label)
pivot-chip has a single reactive property, label, declared with attribute: false — it has no corresponding HTML attribute and must be set as a JS property (chip.label = "..."), never label="..." in markup. The chip’s width grows with its label; there is no truncation or max-width applied by the component itself.
<pivot-chip id="chip-tag"></pivot-chip>
<pivot-chip id="chip-name"></pivot-chip>
<pivot-chip id="chip-email"></pivot-chip>
<script>
document.getElementById("chip-tag").label = "Tag";
document.getElementById("chip-name").label = "Jane Doe";
document.getElementById("chip-email").label = "jane.doe@example.com";
</script>A remove button is always rendered alongside the label — pivot-chip has no property to hide it, so there is no “labels-only” variant.
Removing a chip (pivot-chip-remove)
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. A listener anywhere above the chip (here, on the surrounding container) must remove the corresponding element from its own markup or state.
<div id="chip-remove-bag">
<pivot-chip id="chip-remove-0" data-chip-index="0"></pivot-chip>
<pivot-chip id="chip-remove-1" data-chip-index="1"></pivot-chip>
<pivot-chip id="chip-remove-2" data-chip-index="2"></pivot-chip>
</div>
<script>
const chipRemoveBag = document.getElementById("chip-remove-bag");
const chipRemoveLabels = ["Design", "Engineering", "Research"];
chipRemoveBag.querySelectorAll("pivot-chip").forEach((chip, index) => {
chip.label = chipRemoveLabels[index];
});
chipRemoveBag.addEventListener("pivot-chip-remove", (event) => {
// event.target is the pivot-chip that fired the event — pivot-chip
// carries no detail payload of its own, so identify the chip via the
// target (or a data attribute you set when rendering it) and remove it
// from your own markup/state. pivot-chip will not do this for you.
event.target.remove();
});
</script>Known gap: removing a chip this way does not move focus anywhere afterward. If the remove button had focus when activated, focus is dropped to <body> once its host chip is detached — disorienting for keyboard and screen reader users removing several chips in a row. A production host (e.g. pivot-input) should move focus explicitly after removal — for example to the next remaining chip’s remove button, or back to the originating field.