Skip to content
Kappa
Field
@dicehub/kappav0.4.2

Field

Connects a label, native control, guidance, validation, and field state with one accessible contract.

Workspace setup

Create a workspace

Set the details your team will see.

Use a short name that is easy to scan.
This setting cannot change after creation.
<script setup>
import { ref } from "vue";
import { Field } from "@dicehub/kappa/components/field";
import { Button } from "@dicehub/kappa/components/button";

const name = ref("Northstar");
const region = ref("eu-central");
</script>

<template>
  <form @submit.prevent>
    <Field.Root id="workspace-name" required>
      <Field.Label>
        Workspace name
        <Field.RequiredIndicator />
      </Field.Label>
      <Field.Input v-model="name" autocomplete="organization" />
      <Field.HelperText>Use a short name that is easy to scan.</Field.HelperText>
    </Field.Root>

    <Field.Root id="workspace-region">
      <Field.Label>Data region</Field.Label>
      <Field.Select v-model="region">
        <option value="eu-central">Europe Central</option>
        <option value="us-east">US East</option>
      </Field.Select>
    </Field.Root>

    <Button type="submit">Create workspace</Button>
  </form>
</template>

Installation

Field is part of the main Kappa package and uses the installed Ark UI Field primitive. No additional dependency is required.

Barrel

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

Granular

import { Field } from "@dicehub/kappa/components/field";

Usage

Put the state on Field.Root. Ark UI then connects the label, helper text, error text, and native control through stable IDs and ARIA attributes. Keep the label visible unless the surrounding interface already gives the control a clear name.

We will only use this address for account messages.
<script setup>
import { Field } from "@dicehub/kappa/components/field";
</script>

<template>
  <Field.Root id="email">
    <Field.Label>Email address</Field.Label>
    <Field.Input type="email" autocomplete="email" />
    <Field.HelperText>We will only use this address for account messages.</Field.HelperText>
  </Field.Root>
</template>

Composition

Typical part hierarchy
Field.Root
├── Field.Label
│   └── Field.RequiredIndicator
├── Field.Input / Field.Textarea / Field.Select
├── Field.HelperText
└── Field.ErrorText

Ark UI Field defines field state, generated IDs, live error text, and native control attributes. Kappa adds the compound export, dense control styling, and vertical, horizontal, and responsive layouts.

Guidance and error content stay explicit. Kappa does not include fieldset or group semantics in this component because Ark UI treats a fieldset as a separate primitive.

  • Root owns required, invalid, disabled, and read-only state.
  • Label and RequiredIndicator name and qualify the control.
  • Input, Textarea, and Select are styled native controls.
  • HelperText stays persistent; ErrorText renders only when invalid.
  • Item creates unique control and label IDs inside a multi-control field.

Examples

Basic

Use helper text for stable guidance. Ark UI adds its ID to the control automatically.

We will only use this address for account messages.
<Field.Root id="contact-email">
  <Field.Label>Email address</Field.Label>
  <Field.Input type="email" placeholder="[email protected]" />
  <Field.HelperText>We will only use this address for account messages.</Field.HelperText>
</Field.Root>

Textarea

Set autoresize for content-driven height. Keep a row count as the initial height and use nearby text for limits or format guidance.

45/200 characters
<script setup>
import { ref } from "vue";
import { Field } from "@dicehub/kappa/components/field";

const notes = ref("Bring the accessibility report to the review.");
</script>

<template>
  <Field.Root id="review-notes">
    <Field.Label>Review notes</Field.Label>
    <Field.Textarea v-model="notes" autoresize :rows="3" />
    <Field.HelperText>{{ notes.length }}/200 characters</Field.HelperText>
  </Field.Root>
</template>

Select

Use Select for a small native option list. Use the Kappa Select component for rich options.

Dates and reminders use this timezone.
<Field.Root id="timezone">
  <Field.Label>Timezone</Field.Label>
  <Field.Select v-model="timezone">
    <option value="Europe/Berlin">Berlin (UTC+2)</option>
    <option value="America/New_York">New York (UTC-4)</option>
    <option value="Asia/Singapore">Singapore (UTC+8)</option>
  </Field.Select>
  <Field.HelperText>Dates and reminders use this timezone.</Field.HelperText>
</Field.Root>

Validation

Derive invalid from application validation. ErrorText supports one message or a list. It becomes a polite live region and the control receives aria-errormessage.

Use a unique password for this account.
  • Use at least 8 characters.
  • Add one uppercase letter.
  • Add one number.
<script setup>
import { computed, ref } from "vue";
import { Field } from "@dicehub/kappa/components/field";

const password = ref("short");
const errors = computed(() => {
  const messages = [];
  if (password.value.length < 8) messages.push("Use at least 8 characters.");
  if (!/[A-Z]/.test(password.value)) messages.push("Add one uppercase letter.");
  if (!/\d/.test(password.value)) messages.push("Add one number.");
  return messages;
});
</script>

<template>
  <Field.Root id="password" required :invalid="errors.length > 0">
    <Field.Label>Password <Field.RequiredIndicator /></Field.Label>
    <Field.Input v-model="password" type="password" />
    <Field.HelperText>Use a unique password for this account.</Field.HelperText>
    <Field.ErrorText>
      <ul><li v-for="error in errors" :key="error">{{ error }}</li></ul>
    </Field.ErrorText>
  </Field.Root>
</template>

Required and Optional

RequiredIndicator renders an asterisk only when required is true. Use itsfallback slot when a form needs an explicit optional marker.

<Field.Root id="contact-name" required>
  <Field.Label>Contact name <Field.RequiredIndicator /></Field.Label>
  <Field.Input />
</Field.Root>

<Field.Root id="company-name">
  <Field.Label>
    Company
    <Field.RequiredIndicator>
      <template #fallback><span>(optional)</span></template>
    </Field.RequiredIndicator>
  </Field.Label>
  <Field.Input />
</Field.Root>

Checkbox

Ark UI checkbox and switch controls consume the closest Field context. Their hidden native controls receive the helper, invalid, disabled, and required attributes.

One short email each month. Unsubscribe at any time.
<script setup>
import { Checkbox } from "@dicehub/kappa/components/checkbox";
import { Field } from "@dicehub/kappa/components/field";
</script>

<template>
  <Field.Root id="product-updates">
    <Checkbox.Root default-checked name="product-updates">
      <Checkbox.Control />
      <Field.Label as-child>
        <Checkbox.Label>Send me product updates</Checkbox.Label>
      </Field.Label>
    </Checkbox.Root>
    <Field.HelperText>One short email each month.</Field.HelperText>
  </Field.Root>
</template>

Multiple Controls

Wrap each native control in a renderless Field.Item. Set target on Root when the main label must focus one item. Give every other item its own label.

Set the limit used for monthly alerts.
<Field.Root id="monthly-budget" target="amount">
  <Field.Label>Monthly budget</Field.Label>
  <div class="budget-control">
    <Field.Item value="currency">
      <Field.Label class="visually-hidden">Currency</Field.Label>
      <Field.Select v-model="currency" aria-label="Currency">
        <option>EUR</option>
        <option>USD</option>
        <option>GBP</option>
      </Field.Select>
    </Field.Item>
    <Field.Item value="amount">
      <Field.Input v-model="budget" inputmode="decimal" />
    </Field.Item>
  </div>
  <Field.HelperText>Set the limit used for monthly alerts.</Field.HelperText>
</Field.Root>

Orientation

Horizontal uses two columns. Responsive stays vertical below 40 rem and uses the same two columns on wider surfaces. Vertical is the safe default for narrow or translated forms.

Shown in account menus.
Stacks below 40 rem.
<Field.Root id="account-alias" orientation="horizontal">
  <Field.Label>Account alias</Field.Label>
  <Field.Input />
  <Field.HelperText>Shown in account menus.</Field.HelperText>
</Field.Root>

<Field.Root id="language" orientation="responsive">
  <Field.Label>Language</Field.Label>
  <Field.Select>
    <option>English</option>
    <option>Deutsch</option>
  </Field.Select>
  <Field.HelperText>Stacks below 40 rem.</Field.HelperText>
</Field.Root>

Disabled and Read-only

Disabled controls cannot receive focus or submit a value. Read-only inputs remain focusable and selectable. Native select does not support read-only state.

Disabled while the account is pending.
Contact support to change the owner.
<Field.Root id="customer-id" disabled>
  <Field.Label>Customer ID</Field.Label>
  <Field.Input model-value="CUS-40218" />
  <Field.HelperText>Disabled while the account is pending.</Field.HelperText>
</Field.Root>

<Field.Root id="account-owner" read-only>
  <Field.Label>Account owner</Field.Label>
  <Field.Input model-value="Avery Chen" />
  <Field.HelperText>Contact support to change the owner.</Field.HelperText>
</Field.Root>

Accessibility

  • Use one visible label for each control. Do not use placeholder text as the only label.
  • HelperText is referenced with aria-describedby while it exists.
  • Invalid controls receive aria-invalid and reference ErrorText with aria-errormessage.
  • ErrorText uses aria-live="polite". Do not also place it in another live region.
  • RequiredIndicator is visual and hidden from assistive technology; the native control has required.
  • Use disabled only when the user cannot act. Prefer read-only when they must inspect or copy a value.
  • For multiple controls, use Item and give each non-target control its own accessible label.

API Reference

Field.Root

PropTypeDefaultDescription
orientation"vertical" | "horizontal" | "responsive""vertical"Controls the Kappa label and control layout. Responsive becomes horizontal at 40 rem.
requiredbooleanfalseMarks native controls as required and exposes required state to all parts.
invalidbooleanfalseMarks controls as invalid and renders ErrorText with a polite live region.
disabledbooleanfalseDisables native controls and exposes disabled state to all parts.
readOnlybooleanfalseMakes supported controls read-only while they remain focusable.
idstringgeneratedSets the control ID and the base for generated part IDs.
ids{ root?; control?; label?; errorText?; helperText? }generatedOverrides generated IDs for integration with an existing form system.
targetstring—Points the root label at one Field.Item in a multi-control field.
asChildbooleanfalseMerges root behavior and attributes into one child element.

Native Controls

Native input, textarea, and select attributes and listeners pass through to their elements.

PartPropTypeDescription
Input / Textarea / SelectmodelValuestring | numberControls the native value through v-model.
TextareaautoresizebooleanGrows the textarea with its content and disables manual resize.
All rendered partsasChildbooleanMerges the Ark UI part into one child element.

Parts

PartDescription
Field.RootOwns field IDs, state, ARIA relationships, and layout.
Field.RootProviderRenders a field from a useField machine.
Field.LabelLabels the field control or one Item.
Field.InputNative text input connected to field state.
Field.TextareaNative textarea with optional automatic resize.
Field.SelectNative select connected to field state.
Field.HelperTextPersistent guidance referenced by the control.
Field.ErrorTextInvalid-state message with polite live semantics.
Field.RequiredIndicatorRequired mark with an optional fallback slot.
Field.ItemRenderless context for one control in a multi-control field.
Field.ContextExposes the current Ark field context to a scoped slot.

Exports

ExportDescription
FieldCompound Field component and Root alias.
FieldRootNamed root component.
FieldRootProviderRoot that consumes an external field machine.
FieldLabelNative field label.
FieldInputConnected native input.
FieldTextareaConnected native textarea.
FieldSelectConnected native select.
FieldHelperTextConnected helper text.
FieldErrorTextConnected invalid-state text.
FieldRequiredIndicatorRequired or optional state text.
FieldItemMulti-control field context.
FieldContextScoped field context slot.
useFieldCreates an Ark field machine for RootProvider.
useFieldContextReads the closest field context.
fieldAnatomyArk UI field anatomy metadata.
FIELD_ORIENTATIONSSupported Kappa layout values.
resolveFieldOrientationSafe runtime layout resolver.