Create a workspace
Set the details your team will see.
<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.
<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
Field.Root
├── Field.Label
│ └── Field.RequiredIndicator
├── Field.Input / Field.Textarea / Field.Select
├── Field.HelperText
└── Field.ErrorTextArk 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.
Rootowns required, invalid, disabled, and read-only state.LabelandRequiredIndicatorname and qualify the control.Input,Textarea, andSelectare styled native controls.HelperTextstays persistent;ErrorTextrenders only when invalid.Itemcreates 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.
<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.
<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.
<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 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.
<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.
<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.
<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.
<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-describedbywhile it exists. - Invalid controls receive
aria-invalidand reference ErrorText witharia-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
disabledonly 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
| Prop | Type | Default | Description |
|---|---|---|---|
orientation | "vertical" | "horizontal" | "responsive" | "vertical" | Controls the Kappa label and control layout. Responsive becomes horizontal at 40 rem. |
required | boolean | false | Marks native controls as required and exposes required state to all parts. |
invalid | boolean | false | Marks controls as invalid and renders ErrorText with a polite live region. |
disabled | boolean | false | Disables native controls and exposes disabled state to all parts. |
readOnly | boolean | false | Makes supported controls read-only while they remain focusable. |
id | string | generated | Sets the control ID and the base for generated part IDs. |
ids | { root?; control?; label?; errorText?; helperText? } | generated | Overrides generated IDs for integration with an existing form system. |
target | string | — | Points the root label at one Field.Item in a multi-control field. |
asChild | boolean | false | Merges root behavior and attributes into one child element. |
Native Controls
Native input, textarea, and select attributes and listeners pass through to their elements.
| Part | Prop | Type | Description |
|---|---|---|---|
Input / Textarea / Select | modelValue | string | number | Controls the native value through v-model. |
Textarea | autoresize | boolean | Grows the textarea with its content and disables manual resize. |
All rendered parts | asChild | boolean | Merges the Ark UI part into one child element. |
Parts
| Part | Description |
|---|---|
Field.Root | Owns field IDs, state, ARIA relationships, and layout. |
Field.RootProvider | Renders a field from a useField machine. |
Field.Label | Labels the field control or one Item. |
Field.Input | Native text input connected to field state. |
Field.Textarea | Native textarea with optional automatic resize. |
Field.Select | Native select connected to field state. |
Field.HelperText | Persistent guidance referenced by the control. |
Field.ErrorText | Invalid-state message with polite live semantics. |
Field.RequiredIndicator | Required mark with an optional fallback slot. |
Field.Item | Renderless context for one control in a multi-control field. |
Field.Context | Exposes the current Ark field context to a scoped slot. |
Exports
| Export | Description |
|---|---|
Field | Compound Field component and Root alias. |
FieldRoot | Named root component. |
FieldRootProvider | Root that consumes an external field machine. |
FieldLabel | Native field label. |
FieldInput | Connected native input. |
FieldTextarea | Connected native textarea. |
FieldSelect | Connected native select. |
FieldHelperText | Connected helper text. |
FieldErrorText | Connected invalid-state text. |
FieldRequiredIndicator | Required or optional state text. |
FieldItem | Multi-control field context. |
FieldContext | Scoped field context slot. |
useField | Creates an Ark field machine for RootProvider. |
useFieldContext | Reads the closest field context. |
fieldAnatomy | Ark UI field anatomy metadata. |
FIELD_ORIENTATIONS | Supported Kappa layout values. |
resolveFieldOrientation | Safe runtime layout resolver. |