Fieldset

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

stable · light DOM · 4.0.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.

Markup

<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@4.0.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@4.0.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

Specimen density

Specimen profile

Fieldset `fieldset`

Family: Basic forms
Maturity: stable
Priority: R1
Since: 0.1.0
Native control: native <fieldset> with <legend> — APG pattern
specified
demonstrated

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

Report an issue with this component

Tokens

Focus a role to inspect its values; follow its link for persistent usage and source details.

Part	Role	Value	Use
`root.border`	`color.border.divider`approveduse	`#482b2b`	D-041 border.divider: color.primitive.modern.divider.
`root.bg`	`color.surface.default`approveduse	`#0d0707`	D-041 surface.default: color.primitive.modern.panel.
`legend.text`	`color.text.bright`approveduse	`#ffa2a7`	D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills.
`body.text`	`color.text.default`approveduse	`#e99499`	D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills.
`legend.text-disabled`	`color.text.disabled`approveduse	`#a3676b`	D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills.
`field.bg`	`color.surface.input`approveduse	`#000000`	Form-control fill.
`field.border`	`color.border.control`approveduse	`#c81a1a`	D-041 owner correction: red control and floating-frame borders, distinct from rose text.
`field.bg-disabled`	`color.interaction.disabled.bg`approveduse	`#0d0707`	D-041 interaction.disabled.bg: color.primitive.modern.panel.
`field.border-disabled`	`color.border.disabled`approveduse	`#482b2b`	D-041 border.disabled: color.primitive.modern.divider.
`field.text-disabled`	`color.text.disabled`approveduse	`#a3676b`	D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills.
`help.text`	`color.text.muted`approveduse	`#d4868b`	D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills.

State matrix

Every declared state and combination, statically rendered; the default cell is live. Sizes: compact, comfortable (switch with the density control above).

State	Default
`default`	Window gaps Inner gap Pixels between windows. Outer gap Negative values overlap the screen edge.
`disabled`

Purpose

Groups fields that belong together: an address, a set of credentials, the options of one feature. Checkbox and radio groups use their own components, which are fieldsets too.

Anatomy

Parts as listed in the anatomy. The border is a decorative section rule; 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`; each control takes its own disabled treatment (`color.interaction.disabled.bg`, `color.border.disabled`); border unchanged	`disabled` on the fieldset; cursor: not-allowed on the controls

Keyboard

None of its own; a disabled group’s controls leave the tab order natively.

Accessibility

The legend names the group and is announced before its first field; it says what the group is, not what to do. Groups nest at most two levels. Because disabling hides controls from keyboard users, a disabled group states why in text before it or keeps its controls enabled. Legend, labels and help meet 4.5:1.

Portability

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

Non-examples

No legend, or a visually hidden one. A card instead of a fieldset for form controls. Rounded corners. A 2px or border.control border, which reads as a control. A legend in accent red. Disabling only the legend. Three levels of nesting.

Contrast report

7 declared pairs measured on resolved sRGB values with the WCAG 2.x formula; 0 waived (decorative only), 0 failing. A pass is a design target for the named role, not an application-wide conformance claim.

Pair	State	Kind	Foreground	Background	Ratio	Min	Result
fieldset default text	default	text	`color.text.bright` `#ffa2a7`	`color.surface.default` `#0d0707`	10.45	4.5	pass
group border (decorative; the legend and spacing carry the grouping)	—	ui	`color.border.divider` `#482b2b`	`color.surface.default` `#0d0707`	1.58	1	pass
field labels inside the group	—	text	`color.text.default` `#e99499`	`color.surface.default` `#0d0707`	8.72	4.5	pass
help text inside the group	—	text	`color.text.muted` `#d4868b`	`color.surface.default` `#0d0707`	7.22	4.5	pass
disabled legend and labels (exempt; house floor 3:1)	disabled	ui	`color.text.disabled` `#a3676b`	`color.surface.default` `#0d0707`	4.48	3	pass
disabled field text (exempt; house floor 3:1)	disabled	ui	`color.text.disabled` `#a3676b`	`color.interaction.disabled.bg` `#0d0707`	4.48	3	pass
disabled field border (exempt)	disabled	ui	`color.border.disabled` `#482b2b`	`color.interaction.disabled.bg` `#0d0707`	1.58	1	pass

Keys

Key	Action
`Tab / Shift+Tab`	Moves through the fields inside in document order; the legend is not a tab stop.

For agents

Component JSON ·Implementation brief ·Build a task kit ·

Stress fixtures: FX-LONG FX-320 FX-ZOOM-200 FX-I18N FX-RTL FX-RM FX-HC FX-DENSITY FX-STATE-MATRIX

j3w1 / theme

j3w1 / command

Fieldset

Live variants

default

Install and register

Copy the complete implementation

Public API

attributes

properties

methods

events

Dependencies and verification

Canonical specification

Fieldset `fieldset`

Tokens

State matrix

Purpose

Anatomy

States

Keyboard

Accessibility

Portability

Non-examples

Contrast report

Keys

For agents

Live variants

default

Install and register

Copy the complete implementation

Public API

attributes

properties

methods

events

Dependencies and verification

Canonical specification

Fieldset fieldset

Tokens

State matrix

Purpose

Anatomy

States

Keyboard

Accessibility

Portability

Non-examples

Contrast report

Keys

For agents

Fieldset `fieldset`