J3W1 / DESIGN SYSTEM

Fieldset

The native fieldset that groups related fields under a legend inside a 1px divider border; disabling it disables everything inside.

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

Window gaps

Inner gap

Pixels between windows.

Outer gap

Negative values overlap the screen edge.

<j3w1-fieldset id="example-fieldset-default"><fieldset class="fieldset">
  <legend class="fieldset-legend">Window gaps</legend>
  <div class="fieldset-body">
    <div class="fieldset-field">
      <label class="fieldset-label" for="example-fieldset-default-fs-inner">Inner gap</label>
      <input class="fieldset-input" id="example-fieldset-default-fs-inner" type="text" inputmode="numeric" value="14" aria-describedby="example-fieldset-default-fs-inner-help" name="example-fieldset-default-fs-inner">
      <p class="fieldset-help" id="example-fieldset-default-fs-inner-help">Pixels between windows.</p>
    </div>
    <div class="fieldset-field">
      <label class="fieldset-label" for="example-fieldset-default-fs-outer">Outer gap</label>
      <input class="fieldset-input" id="example-fieldset-default-fs-outer" type="text" inputmode="numeric" value="-2" aria-describedby="example-fieldset-default-fs-outer-help" name="example-fieldset-default-fs-outer">
      <p class="fieldset-help" id="example-fieldset-default-fs-outer-help">Negative values overlap the screen edge.</p>
    </div>
  </div>
</fieldset></j3w1-fieldset>

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

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

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.

methods

Name	Type / signature	Meaning
`refresh`	`(): void`	Reconnect behavior after replacing native child structure.
`focus`	`(options?: FocusOptions): void`	Focus the first usable native control.

events

Name	Type / signature	Meaning

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

Grouping fields that belong together: an address, a set of credentials, the options of one feature. The legend names the group for sighted users and assistive technology alike, and disabling the fieldset disables every control inside it in one step. Checkbox and radio groups use their own components, which are fieldsets too.

Anatomy

The native <fieldset> with a 1px color.border.divider border and 16px padding; the <legend> in color.text.bright sitting in the top border; the fields stacked inside. The border is a section rule, decorative by design; the legend and the spacing carry the grouping.

States

State	Visual	Non-colour channel
default	1px `color.border.divider` border; legend `color.text.bright`; fields as their own components	the border and the legend
disabled	legend and labels `color.text.disabled`; every control inside takes its own disabled treatment (`color.interaction.disabled.bg`, `color.border.disabled`); the border unchanged	`disabled` on the fieldset; cursor: not-allowed on the controls

Keyboard

None of its own. Disabled fieldsets remove their controls from the tab order natively, so a disabled group is skipped rather than walked.

Accessibility

The legend is the accessible name of the group and is announced before the first field inside; it says what the group is, not what to do. A group never nests deeper than two levels. Disabling a group hides its controls from keyboard users, so a disabled group states why in text before it or keeps its controls enabled. Contrast: legend 10.10:1, labels 8.43:1, help 5.66:1 on the panel surface.

Portability

A border and a heading. Hosts without a legend-in-border draw the heading above the box and record it. Disabled propagation is native on the web and in GTK and Qt; a host without it disables each control.

Non-examples

A fieldset with no legend or with a legend hidden visually. A card used instead of a fieldset for form controls. Rounded corners. A 2px or border.control border on the group, which would read as a control. A legend in accent red. Disabling only the legend. Nesting three levels deep.