Fieldset

Native <fieldset> group with legend, description, and error wiring.


Package	`@vizejs/ui/fieldset`
Maturity	stable
Own the source	`vize lib pull fieldset`
Requires	context, field-wiring, id
Aliases	fieldset, field group, legend, radio group wrapper, form section
Covers	HTML fieldset/legend, WAI-ARIA group, React Aria Fieldset

Usage

import { Fieldset, FieldsetLegend, FieldsetDescription, FieldsetErrorMessage } from "@vizejs/ui/fieldset";

Or copy the source into your project with vize lib pull fieldset (see Source Distribution).

API

`Fieldset`

Source: src/families/form/fieldset/fieldset.vue

Props

Prop	Type	Default	Description
`id`	`string \| null`	`undefined`	Fieldset id. `null` and `undefined` select a deterministic fallback.
`name`	`string`	`undefined`	Group name matched against `errors[].name` (for example `"address"`), also set as the native fieldset `name`.
`form`	`string`	`undefined`	Id of a form owner outside the component tree.
`errors`	`readonly FormFieldError[]`	`[]`	Normalized form errors; entries whose `name` equals `name` mark the group invalid.
`invalid`	`boolean`	`undefined`	Consumer-owned invalid override. `undefined` derives it from matching errors.
`disabled`	`boolean`	`false`	Natively disable the fieldset and every descendant form control.
`hasDescription`	`boolean`	`false`	Whether a FieldsetDescription is rendered and joins `aria-describedby`.
`hasErrorMessage`	`boolean`	`true`	Whether a FieldsetErrorMessage is rendered while invalid and joins `aria-describedby`.

Events

Event	Payload	Description
`invalid-change`	`[invalid: boolean, errors: readonly FormFieldError[]]`	Fired after the derived invalid state changes, with the matching errors.

Slots

Slot	Slot props	Description
`default`	`FieldsetSlotState`	Renders the legend, description, fields, and error message with group state.

Exposed

Member	Type	Description
`element`	`Readonly<ShallowRef<HTMLElement \| null>>`	Template ref to the rendered root element.
`invalid`	—
`id`	—

`FieldsetLegend`

Source: src/families/form/fieldset/fieldset-legend.vue

Slots

Slot	Slot props	Description
`default`	`Record<string, never>`	Legend text that names the group; render it as the first child of the Fieldset.

`FieldsetDescription`

Source: src/families/form/fieldset/fieldset-description.vue

Props

Prop	Type	Default	Description
`as`	`PrimitiveAs`	`"p"`	Native element, custom element, or component to render.

Slots

Slot	Slot props	Description
`default`	`Record<string, never>`	Group-level help text; set `hasDescription` on the Fieldset so it is referenced.

`FieldsetErrorMessage`

Source: src/families/form/fieldset/fieldset-error-message.vue

Props

Prop	Type	Default	Description
`as`	`PrimitiveAs`	`"p"`	Native element, custom element, or component to render.
`forceMount`	`boolean`	`false`	Keep the element in the DOM while the group is valid.

Slots

Slot	Slot props	Description
`default`	`FieldsetErrorMessageSlotState`	Group validation text; defaults to the first matching error message.

Behavior

Normative state x input -> outcome table for fieldset.vue, fieldset-legend.vue, fieldset-description.vue, and fieldset-error-message.vue (@vizejs/ui/fieldset). The group is a native <fieldset> named by its <legend>; ids come from the shared field-wiring foundation. Every row is proven by the named test in fieldset.test.ts or fieldset-ssr.test.ts; compile-only assertions live in fieldset.types.test-d.ts.

#	State	Input	Outcome	Proven by
FS1	valid, described	render	native `<fieldset>` with id and `name`, first-child `<legend>`, description id joined into `aria-describedby`, no error	`renders a native fieldset named by its legend and described by its description`
FS2	matching form error	`errors` with the group `name`	group becomes invalid, error message renders with the derived id and joins `aria-describedby`; emits `invalid-change`	`matching form errors mark the group invalid and reference the error message`
FS3	override / disabled	`invalid`, `forceMount`, `disabled`	`invalid` overrides errors; `forceMount` keeps the message; `disabled` is the native attribute that disables descendants	`invalid override, forceMount, and native disabled propagation`
FS4	part without provider	setup	throws the stable `VIZE_UI_CONTEXT_MISSING: Fieldset` diagnostic	`parts require a Fieldset provider`
FS5	SSR / hydration	isolated requests	byte-identical markup with deterministic ids and relations; hydration without diagnostics	`renders byte-identical fieldset markup and hydrates without mismatches`

Public extension contract

Surface	Contract
Parts	`root` (fieldset), `legend`, `description`, `error-message`.
Data attributes	`data-vize-ui`, root `data-state` (`valid`/`invalid`/`disabled`), `data-invalid` on root and legend.
Ids	`<id>-description` and `<id>-error`, matching `useFieldWiring` and `useFormFieldProps` conventions.

The subpath is tree-shakable and ships no CSS; those package contracts are pinned by distribution.test.ts, check:size, and check:tree-shaking.