Kappa / Fieldset

Delivery channelsEmail digestSlack activityChoose the updates that should reach your team.

<script setup>
import { Fieldset } from "@dicehub/kappa/components/fieldset";
</script>

<template>
  <Fieldset.Root id="delivery-channels">
    <Fieldset.Legend>Delivery channels</Fieldset.Legend>
    <label><input type="checkbox" checked /> Email digest</label>
    <label><input type="checkbox" /> Slack activity</label>
    <Fieldset.HelperText>Choose the updates that should reach your team.</Fieldset.HelperText>
  </Fieldset.Root>
</template>

Installation

Fieldset is part of the main Kappa package and uses the installed Ark UI Fieldset primitive.

Barrel

import { Fieldset } from "@dicehub/kappa";

Granular

import { Fieldset } from "@dicehub/kappa/components/fieldset";

Usage

Place one Legend first, then the related controls. Helper and error text describe the complete group.

Contact preferencesEmailPhoneSelect every channel that works for you.

<Fieldset.Root id="contact-preferences">
  <Fieldset.Legend>Contact preferences</Fieldset.Legend>
  <label><input type="checkbox" name="email" /> Email</label>
  <label><input type="checkbox" name="phone" /> Phone</label>
  <Fieldset.HelperText>Select every channel that works for you.</Fieldset.HelperText>
</Fieldset.Root>

Composition

Typical part hierarchy

Fieldset.Root
├── Fieldset.Legend
├── related native controls
├── Fieldset.HelperText
└── Fieldset.ErrorText

Ark UI owns native fieldset and legend semantics, generated IDs, disabled propagation, and polite error messaging. Kappa adds the compound exports, shared styling, and the orientation layout layer.

<script setup>
import {
  FieldsetRoot,
  FieldsetLegend,
  FieldsetHelperText,
} from "@dicehub/kappa/components/fieldset";
</script>

<template>
  <FieldsetRoot>
    <FieldsetLegend>Simulation outputs</FieldsetLegend>
    <label><input type="checkbox" /> Residual plot</label>
    <FieldsetHelperText>Reports are generated after the run completes.</FieldsetHelperText>
  </FieldsetRoot>
</template>

Kappa keeps Fieldset standalone so Checkbox and Radio can compose it without owning the group state.

Examples

Orientation

Vertical stacks direct children. Horizontal uses responsive columns and keeps the legend and messages full width.

Vertical layout Steady state Transient

Horizontal layout Local Cluster

<Fieldset.Root orientation="vertical">
  <Fieldset.Legend>Vertical layout</Fieldset.Legend>
  <label><input type="radio" name="vertical" /> Steady state</label>
  <label><input type="radio" name="vertical" /> Transient</label>
</Fieldset.Root>

<Fieldset.Root orientation="horizontal">
  <Fieldset.Legend>Horizontal layout</Fieldset.Legend>
  <label><input type="radio" name="horizontal" /> Local</label>
  <label><input type="radio" name="horizontal" /> Cluster</label>
</Fieldset.Root>

Validation and Disabled

Invalid renders ErrorText and references it from the group. Native disabled fieldsets disable their descendant controls.

Required channelsAudit logChoose at least one channel.

Locked channels System alertsAvailable to workspace administrators.

<Fieldset.Root id="required-channels" invalid>
  <Fieldset.Legend>Required channels</Fieldset.Legend>
  <label><input type="checkbox" /> Audit log</label>
  <Fieldset.ErrorText>Choose at least one channel.</Fieldset.ErrorText>
</Fieldset.Root>

<Fieldset.Root id="locked-channels" disabled>
  <Fieldset.Legend>Locked channels</Fieldset.Legend>
  <label><input type="checkbox" checked /> System alerts</label>
  <Fieldset.HelperText>Available to workspace administrators.</Fieldset.HelperText>
</Fieldset.Root>

Accessibility

Use one visible Legend to name each group. Do not use a fieldset as a generic layout wrapper.
Keep related controls inside the native fieldset so disabled propagation and group announcement work.
HelperText and ErrorText receive generated IDs and are connected to the fieldset by aria-describedby.
Use invalid with a corrective ErrorText message. ErrorText is a polite live region.
Use disabled when every descendant control is unavailable; native browser behavior remains authoritative.

API Reference

Fieldset.Root

Prop	Type	Default	Description
`orientation`	`"vertical" \| "horizontal"`	`"vertical"`	Stacks direct children or flows them into responsive columns.
`disabled`	`boolean`	`false`	Disables the native fieldset and its form controls.
`invalid`	`boolean`	`false`	Marks the group invalid and enables its ErrorText part.
`id`	`string`	`generated`	Sets the seed used for generated legend, helper, and error part IDs.
`asChild`	`boolean`	`false`	Merges Ark UI root behavior and attributes into one child element.

Parts

Part	Prop	Type	Description
`Legend / HelperText / ErrorText`	`asChild`	`boolean`	Merges the part attributes into one child element.

Composition Parts

Part	Description
`Fieldset.Root`	Native fieldset that owns group state, IDs, and layout.
`Fieldset.RootProvider`	Renders a fieldset from a useFieldset machine.
`Fieldset.Legend`	Native legend that names the control group.
`Fieldset.HelperText`	Persistent guidance referenced by the fieldset.
`Fieldset.ErrorText`	Invalid-state message with polite live semantics.
`Fieldset.Context`	Exposes the current Ark fieldset context to a scoped slot.

Exports

Export	Description
`Fieldset`	Compound Fieldset component and Root alias.
`FieldsetRoot`	Named native fieldset root.
`FieldsetRootProvider`	Root that consumes an external fieldset machine.
`FieldsetLegend`	Named native legend part.
`FieldsetHelperText`	Named helper text part.
`FieldsetErrorText`	Named invalid-state text part.
`FieldsetContext`	Scoped fieldset context slot.
`useFieldset`	Creates an Ark fieldset machine for RootProvider.
`useFieldsetContext`	Reads the closest fieldset context.
`fieldsetAnatomy`	Ark UI fieldset anatomy metadata.
`FIELDSET_ORIENTATIONS`	Supported Kappa layout values.
`resolveFieldsetOrientation`	Safe runtime layout resolver.