Forms & Input
Field
Composable form layout — FieldSet, FieldGroup, FieldLabel, FieldDescription, FieldError, FieldTitle, FieldContent, FieldSeparator (shadcn-aligned). Legacy label/description/error props on Field remain supported. Make the expected input clear before someone interacts, and keep the current value, help text and validation feedback connected. Import it from @/components/kamod-ui/field.
Source · Design reference · API reference · Theming · Styles
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthInstallation
Import Field and subcomponents from @/components/kamod-ui/field (FieldSet, FieldGroup, FieldLabel, FieldDescription, FieldError, …).
pnpm add @kamod-ch/uiCopy an example with @kamod-ch/ui or the matching @kamod-ch/ui/… subpath. The code block switches between those two installs. Connect The Global Theme CSS and Tailwind Source Detection before your first render.
Usage
Compose Field around controls. Use FieldSet + FieldLegend for semantics. Field orientation horizontal for checkbox/radio + label rows. FieldLabel can wrap a Field for choice cards. Field still accepts label, description, and error props for quick stacks (legacy).
import { Field } from "@kamod-ch/ui";Choose a complete composition from the examples below; required child components and props vary by pattern.
Component Examples & Variants
Explore Field in Different Contexts, from the starting pattern to the compositions below. Begin with Anatomy, then compare the examples that match your content, state and layout. These are working patterns to adapt, not a list of interchangeable variant values: check the API Reference before using a prop or combining behaviors. Look at the surrounding labels, supporting text and spacing as well as the component itself.
Read the Result and Its Implementation Together. Use each showcase’s Code view to inspect imports and composition, or its Prompt view to prepare a setup or adaptation brief. Try the narrow preview and local theme controls before connecting real data, and use Reset to return an example to its initial state. Keep layout changes in class utilities where appropriate; follow the Component Styles Guide for hierarchy and the Theming Guide for shared surfaces and colors. The Accessibility Notes explain what to preserve when making those changes.
Anatomy
Build the Relationships before the Styling. Compose FieldSet, FieldGroup, the label, control, description and error in their intended reading order. The example shows which wrapper organizes a question and which element owns the actual editable value.
Preserve stable identifiers and accessible associations when rearranging these parts; the Accessibility Notes describe what to verify after composing a complete form.
import { Field, FieldDescription, FieldError, FieldGroup, FieldLabel, FieldLegend, FieldSet, Input } from "@kamod-ch/ui";
export const Example = () => (
<FieldSet class="w-full max-w-xs">
<FieldLegend>Profile</FieldLegend>
<FieldDescription>This appears on invoices and emails.</FieldDescription>
<FieldGroup>
<Field>
<FieldLabel htmlFor="name">Full name</FieldLabel>
<Input id="name" autoComplete="off" placeholder="Evil Rabbit" />
<FieldDescription>This appears on invoices and emails.</FieldDescription>
</Field>
<Field invalid>
<FieldLabel htmlFor="username">Username</FieldLabel>
<Input id="username" autoComplete="off" aria-invalid />
<FieldError>Choose another username.</FieldError>
</Field>
<Field orientation="horizontal">
<Checkbox id="newsletter" />
<FieldLabel htmlFor="newsletter">Subscribe to the newsletter</FieldLabel>
</Field>
</FieldGroup>
</FieldSet>
);Legacy Props
Keep Simple Field Composition Concise. Use Field with label, description and error props when maintaining the compact wrapper API. It packages common field content while the child control remains responsible for its own value and interaction behavior.
Use the compound pieces for richer layouts, and check the resulting associations rather than assuming that visible proximity alone connects the text to a custom control.
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthInput
Choose Input Semantics for the Actual Value. Group username and password inputs with their visible labels and supporting instructions. Each Field describes one value, making it possible to attach validation feedback locally rather than explaining every problem at the form's top.
Keep hints outside placeholder text and let the field wrapper organize the message; the underlying input still owns its value, type and browser behavior.
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthTextarea
Leave Room for a Longer Answer. Place a multiline control in Field when the answer needs more room than a single line. Pair its label with concise instructions about the expected content, keeping those instructions separate from any validation error.
Keep the label visible while typing, associate errors with the textarea, and avoid making the initial height so small that ordinary responses become difficult to review.
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthSelect
Label the Selection Rather than Its Placeholder. Wrap Select in a field structure that names the question and describes the available choice. Associate the label with the select trigger so the surrounding layout and the interactive control communicate the same purpose.
Connect help and validation to the control, use stable option values, and inspect Select for grouped and unavailable-choice patterns.
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthSlider
Explain the Value and Its Unit. Use FieldTitle and FieldDescription around a Slider when the value is chosen along a range. Explain the scale and current value in text so the thumb's position is not the only way to interpret the setting.
Name the actual slider control as well as the surrounding field, choose a meaningful step, and avoid requiring precise values that are difficult to select by dragging alone.
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthFieldset
Group Controls that Answer One Larger Question. Use a fieldset legend to introduce several inputs that answer one larger question. A description and grid layout can then organize the individual values without repeating the group's explanation beside every control.
Keep the shared description separate from field-specific errors and preserve a sensible reading order when changing the grid from multiple columns to a narrow single-column layout.
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthCheckbox
Keep the Choice and Its Explanation Together. Arrange checkbox fields horizontally with FieldContent holding the label and explanation beside each control. This gives longer preference descriptions room to wrap while preserving a clear association with the corresponding checked state.
Preserve label activation and description associations, and ensure wrapped copy aligns naturally without shrinking the checkbox or separating it from the words that explain its state.
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthRadio
Name the Question and Each Exclusive Answer. Place RadioGroup inside FieldSet when several options answer one mutually exclusive question. The legend names the choice, while each option's label explains one value that may be selected.
Keep the options in one logical group, use stable submitted values, and avoid presenting several independently labeled controls when only one answer is allowed.
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthSwitch
Describe the Setting in Its Enabled State. Pair a Switch with a label in a horizontal field for a boolean preference. The label explains what enabling the setting does, while the switch displays the current value supplied by the application.
Explain whether changes apply immediately or require saving, and keep the label tied to the actual switch so both the wording and control activate the same setting.
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthChoice Card
Make a Larger Option Easier to Scan and Select. Wrap the radio field in FieldLabel to make the choice-card surface part of the labeled option. The larger target accommodates supporting details while the radio control still represents one value in the shared group.
Keep the entire selection relationship clear, avoid nested unrelated actions, and make selected state visible through more than a subtle background change.
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthField Group + Separator
Break Long Forms into Meaningful Sections. Stack related fieldsets and insert FieldSeparator between distinct topics in a longer form. This adds a quiet structural break without changing the association between each group's legend and its controls.
Preserve the same logical order on narrow screens, and keep validation messages near their fields instead of collecting all feedback between sections.
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthFieldError (Errors Array)
Show Useful Validation Feedback without Duplication. Pass an errors array to FieldError when validation produces structured messages for a field. The error component presents that feedback; the form integration remains responsible for deciding which messages belong to the current value.
Connect the rendered error to its control and decide when it appears, especially after the first unsuccessful submit.
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthResponsive Orientation
Adapt to the Form Container, Not Only the Screen. Use the responsive field orientation inside a container-aware FieldGroup. The layout stacks at narrow widths and changes at @md, adapting to its actual available space rather than assuming the full page width.
Test long labels and errors in each arrangement, and preserve the DOM reading order so the visual switch does not change the meaning of the form.
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthLegacy Error
Keep the Correction Close to the Input. Supply the legacy error prop when using the compact Field wrapper's validation presentation. Keep the message tied to the actual failed rule and update it when the underlying value is corrected.
Associate the feedback with the control through aria-describedby where appropriate, and expose its invalid state with aria-invalid. Try submitting an empty value and then correcting it to check the entire feedback cycle.
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthProps and Data
Configure Field using the contracts below. Read the documented options alongside the Source Definitions to understand which values your application supplies and which details the component owns. Start with a prop or helper, then follow its type link to inspect the declaration without leaving the page.
Props, slots and variants for this component.
Type cards are extracted from this checkout’s TypeScript source at build time. Props inherited through HTMLAttributes, Omit or variant helpers remain references in those declarations; their fields are not flattened here. Match the reference to your installed version, and check a package’s exports before writing an import type. A type exported by a source file is not necessarily re-exported by @kamod-ch/ui.
Component Props
? means a field can be omitted; it does not promise a fallback value. Existing documented defaults remain alongside the descriptions. For callbacks, check the argument and return types before connecting your own state or services.Field
FieldProps
| Prop / type | Description |
|---|---|
children | Configure
|
class | Configure
|
description | Legacy: helper below control.
|
disabled | Configure
|
error | Legacy: error below control.
|
invalid | Configure
|
label | Legacy: label text/node (composition: use FieldLabel instead).
|
orientation | Configure
|
required | Configure
|
FieldContent
FieldContentProps
| Prop / type | Description |
|---|---|
children | Configure
|
class | Configure
|
FieldDescription
FieldDescriptionProps
| Prop / type | Description |
|---|---|
children | Configure
|
class | Configure
|
FieldError
FieldErrorProps
| Prop / type | Description |
|---|---|
children | Configure
|
class | Configure
|
errors | Configure
|
FieldGroup
FieldGroupProps
| Prop / type | Description |
|---|---|
children | Configure
|
class | Configure
|
FieldLabel
FieldLabelProps
| Prop / type | Description |
|---|---|
class | Configure
|
FieldLegend
FieldLegendProps
| Prop / type | Description |
|---|---|
class | Configure
|
variant | Configure
|
FieldSeparator
FieldSeparatorProps
| Prop / type | Description |
|---|---|
children | Configure
|
class | Configure
|
FieldSet
FieldSetProps
| Prop / type | Description |
|---|---|
class | Configure
|
FieldTitle
FieldTitleProps
| Prop / type | Description |
|---|---|
children | Configure
|
class | Configure
|
Data Type Reference
Expand a card to inspect and copy the exact declaration. The code header identifies its repository file; follow imported or inherited types in the Implementation Source when you need the complete dependency chain. Required-field summaries cover fields declared directly in that type. Source-only helpers and inferred schema outputs describe the local implementation, not additional props you can pass to every component.
Field Props
8 declared fieldsFieldPropsField.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of FieldProps before adapting it.FieldContent Props
1 declared fieldFieldContentPropsFieldContent.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of FieldContentProps before adapting it.FieldDescription Props
1 declared fieldFieldDescriptionPropsFieldDescription.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of FieldDescriptionProps before adapting it.FieldError Props
2 declared fieldsFieldErrorPropsFieldError.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of FieldErrorProps before adapting it.FieldGroup Props
1 declared fieldFieldGroupPropsFieldGroup.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of FieldGroupProps before adapting it.FieldLabel Props
DeclarationFieldLabelPropsFieldLabel.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of FieldLabelProps before adapting it.FieldLegend Props
DeclarationFieldLegendPropsFieldLegend.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of FieldLegendProps before adapting it.FieldSeparator Props
1 declared fieldFieldSeparatorPropsFieldSeparator.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of FieldSeparatorProps before adapting it.FieldSet Props
DeclarationFieldSetPropsFieldSet.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of FieldSetProps before adapting it.FieldTitle Props
1 declared fieldFieldTitlePropsFieldTitle.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of FieldTitleProps before adapting it.FieldRootVariants
DeclarationFieldRootVariantsfield-variants.ts. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of FieldRootVariants before adapting it.Accessibility
Build the Complete Interaction, Including the Parts Outside Field. The notes below distinguish the current implementation from the labels, content and behavior your application supplies. Start with the Live Preview, check the Props and Data Reference, and test the finished composition with real content rather than assuming that an unchanged visual example covers every use case.
Built-in Behavior and Defaults
Field provides layout and visual states. invalid, disabled and required on the wrapper do not automatically configure the nested control. FieldError uses role="alert"; FieldSet and FieldLegend provide native grouping when composed around related inputs.
Labels and Relationships
Prefer explicit composition with FieldLabel htmlFor, a control id, and IDs on FieldDescription and FieldError. Reference those IDs from the control using aria-describedby. The legacy label prop renders a separate label without automatically associating it with a child input.
Keyboard and Focus
Keep a group question in FieldLegend and give each individual option its own label. Put disabled or required on the actual input where appropriate. Changing a wrapper's appearance must not leave the contained input behaving differently from what the user sees.
States and Integration Details
Mount error feedback when it becomes relevant, and avoid multiple nested alert regions for the same message. A visible error and an accessible description solve different problems: one must not be substituted for the other.
Verify the Complete Interaction
Check Behavior as Well as Markup. Work through these scenarios in the application where the component will be used. Automated checks can help find structural problems; also review the reading experience with a screen reader, keyboard focus and the actual feedback from your application.
- Activate every visible field label and confirm it targets the intended control rather than another form instance.
- Inspect the actual input for required, disabled and invalid states; do not stop at wrapper data attributes.
- Submit, correct and resubmit while checking error announcements for missing or duplicate messages.
Recheck the result after changing Theme Tokens, translations or class overrides. Include text enlargement, narrow layouts and reduced-motion settings where animation is present. Inspect the Component Source when a behavior differs from your expectation; a role or state attribute does not implement keyboard interaction by itself.
For background, read the WAI-ARIA Authoring Guidance and Keyboard Interface Guidance. These explain the patterns; verify browser and assistive-technology behavior for the implementation and audience you actually support.
You have the pieces. Put them into one real interaction, keep its state in one place, and check the result with the content your application will actually show.
Connect the Foundation
Return to Choose and Compose Components to connect this reference to a working screen. Keep global CSS in one entrypoint and import only the components that screen needs.
Build the Surrounding Screen
Find a neighboring interaction in the Component Library, or start with a complete Block. Replace sample content and destinations before refining the layout; a local class change can stay with the composition.
Make the Result Hold Up
Use shared theme roles for changes that belong everywhere. Then review the whole journey: keyboard focus, long labels, narrow screens and a clear way to recover when something fails.
Keep a link to the source and note your intentional changes. Your next edit should begin with a clear decision, not another search.