J3W1 / DESIGN SYSTEM

Repeater

Repeat native field rows with stable identities and keyboard ordering.

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

No contacts added.

<j3w1-repeater id="example-repeater-default" max="10"><section class="repeater" aria-label="Additional contacts"><ol data-rows=""></ol><template data-row-template=""><li class="repeater-item"><label for="example-repeater-default-contact-name">Contact name</label><input class="repeater-control" id="example-repeater-default-contact-name" name="example-repeater-default-contact" required=""><div class="repeater-actions"><button class="repeater-control" type="button" data-move="-1">Move up</button><button class="repeater-control" type="button" data-move="1">Move down</button><button class="repeater-control" type="button" data-remove="">Remove</button></div></li></template><p data-empty="">No contacts added.</p><button class="repeater-control" type="button" data-add="" data-demo-focus-target="">Add contact</button><p role="status" data-repeater-status=""></p></section></j3w1-repeater>

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/repeater.css';
import '@j3w1/ui/register/repeater';

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 repeater --out ./vendor/j3w1/repeater

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.
`max`	`CustomEvent`	Maximum rows, default 10; positive integer up to 100.

properties

Name	Type / signature	Meaning
`disabled`	`boolean`	Delegates disabled state to native children.
`name`	`string`	Native control name; application form keys remain explicit.
`rowIds`	`string[]`	Stable IDs in current source order. Read only.

methods

Name	Type / signature	Meaning
`refresh`	`(): void`	Reconnect behavior after replacing native child structure.
`focus`	`(options?: FocusOptions): void`	Focus the first usable native control.
`add`	`(): string \| null`	Append a row when below the configured limit.
`remove`	`(id: string): void`	Remove a known row and recover focus.
`move`	`(id: string, direction: number): void`	Move a row one position up or down.

events

Name	Type / signature	Meaning
`j3w1-rows`	`CustomEvent`	Row order or membership changed.

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

Repeat native fields from trusted inert HTML. Add, remove and reorder preserve row identities. The host supplies fields and handles submission; the component does not execute a schema or provide persistence. A max attribute bounds the number of rows; the supplied example is limited to ten.

Anatomy

rows: Ordered list of independently named field rows.
template: Trusted native markup cloned on explicit Add.
actions: Add, remove, move up and move down; no drag-only behavior.

States

State	Presentation	Non-colour channel
default	Named content on the default surface.	Native text and structure.
empty	A muted empty message.	Explicit text and retained Add action.
focus-visible	Dashed focus ring.	Native keyboard focus position.
disabled	Disabled semantic foreground, background and border at full opacity.	Native disabled state blocks activation.

Keyboard

Tab / Shift+Tab: Visit fields and row actions in source order.
Enter / Space: Add, remove or move a row. Focus follows the affected row or nearest survivor.

Accessibility

Namespace IDs and label/ARIA references for each row. Row identities do not change during reordering. Actions have names and disabled boundary states. Removing a focused row restores focus to a surviving row or Add; announce each explicit operation.

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.