J3W1 / DESIGN SYSTEM

Multiple selection

A searchable native checkbox group that preserves all selected form values.

stable · LIGHT DOM · 1.1.0

Light DOM retains static content, native semantics, label relationships and host composition without duplicating controls.

Standalone example ↗Copy file manifest Canonical JSON Vue gallery ↗Prepare an agent kit →

Live variants

default

Notification topicsFilter topics

ReleasesComponentsGuides

3 topics; 1 selected

<j3w1-multiselect id="example-multiselect-default"><fieldset class="multiselect checkbox checkbox-group"><legend class="checkbox-legend">Notification topics</legend><label for="example-multiselect-default-multiselect-search">Filter topics</label><input class="multiselect-control" id="example-multiselect-default-multiselect-search" type="search" data-filter="" data-demo-focus-target=""><button class="multiselect-control" type="button" data-clear-selection="">Clear selection</button><div data-options=""><label class="checkbox-option"><span class="checkbox-control"><input class="checkbox-input" type="checkbox" name="example-multiselect-default-topics" value="releases" checked=""><svg class="checkbox-check" aria-hidden="true" viewBox="0 0 16 16" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.5"><path d="M3.5 8.5l3 3 6-6"></path></svg></span><span class="checkbox-text">Releases</span></label><label class="checkbox-option"><span class="checkbox-control"><input class="checkbox-input" type="checkbox" name="example-multiselect-default-topics" value="components"><svg class="checkbox-check" aria-hidden="true" viewBox="0 0 16 16" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.5"><path d="M3.5 8.5l3 3 6-6"></path></svg></span><span class="checkbox-text">Components</span></label><label class="checkbox-option"><span class="checkbox-control"><input class="checkbox-input" type="checkbox" name="example-multiselect-default-topics" value="guides"><svg class="checkbox-check" aria-hidden="true" viewBox="0 0 16 16" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.5"><path d="M3.5 8.5l3 3 6-6"></path></svg></span><span class="checkbox-text">Guides</span></label></div><p role="status" data-selection-status="">3 topics; 1 selected</p></fieldset></j3w1-multiselect>

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.0

import '@j3w1/ui/tokens.css';
import '@j3w1/ui/styles/multiselect.css';
import '@j3w1/ui/register/multiselect';

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.

Vue SFC, React, Astro and plain HTML integration →

Copy the complete implementation

npx --package=@j3w1/ui@1.1.0 j3w1-ui copy multiselect --out ./vendor/j3w1/multiselect

The 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.
`values`	`string[]`	Selected native checkbox values, including hidden matches.

methods

Name	Type / signature	Meaning
`refresh`	`(): void`	Reconnect behavior after replacing native child structure.
`focus`	`(options?: FocusOptions): void`	Focus the first usable native control.
`clear`	`(): void`	Clear every selected value and report the explicit change.

events

Name	Type / signature	Meaning
`j3w1-selection`	`CustomEvent`	The selected values changed through interaction.

Dependencies and verification

Registered components: none. Style dependencies: checkbox.

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

Select zero or more named values using a labelled native checkbox list. Local search filters visible choices without clearing selections. Successful checkboxes retain repeated native form keys. Clear selection is an explicit action.

Anatomy

group: Fieldset and legend name the choice.
filter: Labelled search input filters option labels.
options: Native checkboxes remain selected when filtered out.
status: Visible count distinguishes matching options from selected values.

States

State	Presentation	Non-colour channel
default	Named content on the default surface.	Native text and structure.
checked	Selected fill and a check indicator.	Native checked state.
focus-visible	Dashed focus ring.	Native keyboard focus position.
disabled	Disabled semantic foreground, background and border at full opacity.	Native disabled state blocks activation.
no-results	Muted result count.	Zero-results text; existing selected values remain selected.

Keyboard

Tab / Shift+Tab: Visit search, clear and each visible enabled checkbox.
Space: Toggle the focused checkbox.
Escape: Clear a non-empty query without clearing selection.

Accessibility

Keep labels and native checkbox semantics. Hidden choices leave the focus order but retain checked form values. Announce matching and selected counts, including zero. Required selection policy belongs to the host; marking every checkbox required would require every option.

Portability

Wrap labels and actions without changing source order. Use logical spacing in RTL. Preserve native target sizes at both densities; only bounded data regions may scroll horizontally. Use equivalent native semantics and approved roles; record any unsupported behavior as a mapping deviation. The host owns application data, persistence, permissions and services.

Non-examples

Unlabelled controls, color-only status, drag-only operations, hidden required instructions, stolen focus or an invented service success.