J3W1 / DESIGN SYSTEM
Chip
A square bordered token for a filter, a removable value or a static tag; a pressed filter chip takes the selection fill and a check glyph.
stable · LIGHT DOM · 1.1.0
Light DOM retains static content, native semantics, label relationships and host composition without duplicating controls.
Live variants
filter
<j3w1-chip id="example-chip-filter"><button class="chip chip-filter" type="button" aria-pressed="false"><span class="chip-check" aria-hidden="true">✓</span><span class="chip-label">Navigation</span></button></j3w1-chip>removable
<j3w1-chip id="example-chip-removable"><span class="chip chip-removable"><span class="chip-label">tabs</span><button class="chip-remove" type="button" aria-label="Remove tabs"><span aria-hidden="true">×</span></button></span></j3w1-chip>static
<j3w1-chip id="example-chip-static"><span class="chip chip-static"><span class="chip-label">R1</span></span></j3w1-chip>Install and register
Use the exact version. If npm publication is pending, install the release tarball from the installation guide.
npm install --save-exact @j3w1/ui@1.1.0import '@j3w1/ui/tokens.css';
import '@j3w1/ui/styles/chip.css';
import '@j3w1/ui/register/chip';Insert the maintained markup above after loading these imports. Its native children provide accessible names and form behavior; the empty custom tag alone does not create a control.
Copy the complete implementation
npx --package=@j3w1/ui@1.1.0 j3w1-ui copy chip --out ./vendor/j3w1/chipThe CLI verifies every file before writing and refuses overwrites. Serve the output over HTTP and open index.html. Keep its modules, CSS, tokens and licence notices together.
Public API
attributes
| Name | Type / signature | Meaning |
|---|---|---|
disabled | CustomEvent | Disable the native controls owned by this instance. |
loading | CustomEvent | Mark the primary control busy and prevent duplicate activation. |
properties
| Name | Type / signature | Meaning |
|---|---|---|
disabled | boolean | Delegates disabled state to native children. |
name | string | Native control name; application form keys remain explicit. |
methods
| Name | Type / signature | Meaning |
|---|---|---|
refresh | (): void | Reconnect behavior after replacing native child structure. |
focus | (options?: FocusOptions): void | Focus the first usable native control. |
dismiss | (id?: string): void | Dismiss a message; focused actions move to the next available control. |
events
| Name | Type / signature | Meaning |
|---|---|---|
j3w1-dismiss | CustomEvent | Cancelable message dismissal. |
j3w1-retry | CustomEvent | Request recovery; the host owns the result. |
j3w1-action | CustomEvent | An explicit message action. |
Dependencies and verification
Registered components: none. Style dependencies: none.
Package presence establishes an available implementation. Actual passes depend on the tested artifact and environment. Read specification execution evidence; read packed-consumer evidence; inspect the complete state matrix.
Full implementation manifest, API and token dependency closure
Canonical specification
Purpose
Represents one value the user can toggle or remove: a filter in a filterable table, a chosen item in a multiselect, a tag on a record. A chip that only informs is a badge; a chip that runs an action is a button.
Anatomy
A square control-height box with 1px color.border.control on
color.surface.default and text in color.text.default. A filter chip is a
button with a check gutter that shows ✓ while pressed. A removable chip is a
span holding the label and a × button in color.text.muted. A static chip is
a span with nothing else. When selected, the chip fills with
color.interaction.selection.bg and its text becomes
color.interaction.selection.text.
States
| State | Visual | Non-colour channel |
|---|---|---|
| default | 1px color.border.control on color.surface.default; text color.text.default | — |
| hover | background → color.interaction.hover.bg; the remove button → color.interaction.hover.bg-strong with color.text.bright | cursor: pointer |
| focus-visible | ring 1px dashed color.interaction.focus.ring at −2px on the chip or on the remove button | the ring |
| selected | fill color.interaction.selection.bg; text and glyph color.interaction.selection.text; the border takes the fill colour | aria-pressed="true"; the ✓ glyph |
| selected+focus-visible | the fill and the ring in color.interaction.focus.ring-container | both visible at once |
| disabled | text color.text.disabled; border color.border.disabled; background color.interaction.disabled.bg; no hover | disabled; cursor: not-allowed |
Pressing a filter chip uses color.interaction.pressed.bg for the duration
of the press only. Precedence: disabled > selected > hover; focus-visible is
always drawn.
Keyboard
A filter chip is one tab stop that toggles on Space or Enter. A removable chip contributes only its remove button to the tab order; the label is not focusable. A static chip is never focusable. Inside a token field the field owns Backspace and the arrow keys.
Accessibility
Filter chips expose aria-pressed and keep the same label in both states;
the ✓ glyph is aria-hidden. The remove button is named “Remove compact density with 4px between neighbours.
Portability
A bordered box with a background and an outline; the remove control is an ordinary small button. Toolkits with a native toggle button take the fill for the checked state. Hosts without a glyph draw the check as a 2px inset rule at the inline start and record it.
Non-examples
Pill or rounded chips. A selected chip shown by a border colour alone
without the fill and aria-pressed. A removable chip whose × has no name.
A chip that is a link. A static tag that reacts to hover. Disabling by
opacity. A chip whose label clips inside the border. A chip in caption
type (that is a badge).