Your next page is taking shape...

Opening Your Next Page…

Loading the guide and preparing its examples for you to explore. The page will appear here automatically when it’s ready, so you can keep this view open without refreshing.

Made for Preact. Built to be yours.

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 Live Preview
Try it. Make it yours.
Setting the scene...

Interactive preview

Live Preact example Local preview theme · Responsive styles follow the preview widthFull width

Installation

Import Field and subcomponents from @/components/kamod-ui/field (FieldSet, FieldGroup, FieldLabel, FieldDescription, FieldError, …).

Install PackagesTerminal
pnpm add @kamod-ch/ui

Copy 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 SetupTypeScript
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.

src/components/FieldExample.tsx24 lines
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 Live Preview
Try it. Make it yours.
Setting the scene...

Interactive preview

Live Preact example Local preview theme · Responsive styles follow the preview widthFull width

Input

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 Live Preview
Try it. Make it yours.
Setting the scene...

Interactive preview

Live Preact example Local preview theme · Responsive styles follow the preview widthFull width

Textarea

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 Live Preview
Try it. Make it yours.
Setting the scene...

Interactive preview

Live Preact example Local preview theme · Responsive styles follow the preview widthFull width

Select

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 Live Preview
Try it. Make it yours.
Setting the scene...

Interactive preview

Live Preact example Local preview theme · Responsive styles follow the preview widthFull width

Slider

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 Live Preview
Try it. Make it yours.
Setting the scene...

Interactive preview

Live Preact example Local preview theme · Responsive styles follow the preview widthFull width

Fieldset

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 Live Preview
Try it. Make it yours.
Setting the scene...

Interactive preview

Live Preact example Local preview theme · Responsive styles follow the preview widthFull width

Checkbox

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 Live Preview
Try it. Make it yours.
Setting the scene...

Interactive preview

Live Preact example Local preview theme · Responsive styles follow the preview widthFull width

Radio

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 Live Preview
Try it. Make it yours.
Setting the scene...

Interactive preview

Live Preact example Local preview theme · Responsive styles follow the preview widthFull width

Switch

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 Live Preview
Try it. Make it yours.
Setting the scene...

Interactive preview

Live Preact example Local preview theme · Responsive styles follow the preview widthFull width

Choice 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 Live Preview
Try it. Make it yours.
Setting the scene...

Interactive preview

Live Preact example Local preview theme · Responsive styles follow the preview widthFull width

Field 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 Live Preview
Try it. Make it yours.
Setting the scene...

Interactive preview

Live Preact example Local preview theme · Responsive styles follow the preview widthFull width

FieldError (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 Live Preview
Try it. Make it yours.
Setting the scene...

Interactive preview

Live Preact example Local preview theme · Responsive styles follow the preview widthFull width

Responsive 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 Live Preview
Try it. Make it yours.
Setting the scene...

Interactive preview

Live Preact example Local preview theme · Responsive styles follow the preview widthFull width

Legacy 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 Live Preview
Try it. Make it yours.
Setting the scene...

Interactive preview

Live Preact example Local preview theme · Responsive styles follow the preview widthFull width
API reference

Props 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.

API reference
Your API, from source

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

Read each option with its owning component. The
marker identifies required fields verified in that declaration. A ? 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.
@kamod-ch/ui/field10.3 KB min · 2.6 KB gzipSignals: none

Field

FieldProps

Field documented props
Prop / typeDescription
children
ComponentChild[] | ComponentChildFieldProps

Configure children for Field. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—
class
string | SignalLike<string | undefined>FieldProps

Configure class for Field. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—
description
ComponentChild[] | ComponentChildFieldProps

Legacy: helper below control.

Default
—
disabled
booleanFieldProps

Configure disabled for Field. Compare its accepted type with the Usage Guidance before supplying a value.

Default
false
error
ComponentChild[] | ComponentChildFieldProps

Legacy: error below control.

Default
—
invalid
booleanFieldProps

Configure invalid for Field. Compare its accepted type with the Usage Guidance before supplying a value.

Default
false
label
ComponentChild[] | ComponentChildFieldProps

Legacy: label text/node (composition: use FieldLabel instead).

Default
—
orientation
"horizontal" | "vertical" | "responsive"FieldProps

Configure orientation for Field. Compare its accepted type with the Usage Guidance before supplying a value.

Default
"vertical"
required
booleanFieldProps

Configure required for Field. Compare its accepted type with the Usage Guidance before supplying a value.

Default
false

FieldContent

FieldContentProps

FieldContent documented props
Prop / typeDescription
children
ComponentChild[] | ComponentChildFieldContentProps

Configure children for FieldContent. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—
class
string | SignalLike<string | undefined>FieldContentProps

Configure class for FieldContent. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—

FieldDescription

FieldDescriptionProps

FieldDescription documented props
Prop / typeDescription
children
ComponentChild[] | ComponentChildFieldDescriptionProps

Configure children for FieldDescription. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—
class
string | SignalLike<string | undefined>FieldDescriptionProps

Configure class for FieldDescription. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—

FieldError

FieldErrorProps

FieldError documented props
Prop / typeDescription
children
ComponentChild[] | ComponentChildFieldErrorProps

Configure children for FieldError. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—
class
string | SignalLike<string | undefined>FieldErrorProps

Configure class for FieldError. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—
errors
({ message?: string; } | undefined)[]FieldErrorProps

Configure errors for FieldError. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—

FieldGroup

FieldGroupProps

FieldGroup documented props
Prop / typeDescription
children
ComponentChild[] | ComponentChildFieldGroupProps

Configure children for FieldGroup. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—
class
string | SignalLike<string | undefined>FieldGroupProps

Configure class for FieldGroup. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—

FieldLabel

FieldLabelProps

FieldLabel documented props
Prop / typeDescription
class
string | SignalLike<string | undefined>FieldLabelProps

Configure class for FieldLabel. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—

FieldLegend

FieldLegendProps

FieldLegend documented props
Prop / typeDescription
class
string | SignalLike<string | undefined>FieldLegendProps

Configure class for FieldLegend. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—
variant
"legend" | "label"FieldLegendProps

Configure variant for FieldLegend. Compare its accepted type with the Usage Guidance before supplying a value.

Default
"legend"

FieldSeparator

FieldSeparatorProps

FieldSeparator documented props
Prop / typeDescription
children
ComponentChild[] | ComponentChildFieldSeparatorProps

Configure children for FieldSeparator. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—
class
string | SignalLike<string | undefined>FieldSeparatorProps

Configure class for FieldSeparator. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—

FieldSet

FieldSetProps

FieldSet documented props
Prop / typeDescription
class
string | SignalLike<string | undefined>FieldSetProps

Configure class for FieldSet. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—

FieldTitle

FieldTitleProps

FieldTitle documented props
Prop / typeDescription
children
ComponentChild[] | ComponentChildFieldTitleProps

Configure children for FieldTitle. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—
class
string | SignalLike<string | undefined>FieldTitleProps

Configure class for FieldTitle. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—

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 fields
FieldProps
Exported Source Declaration from Field.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 field
FieldContentProps
Exported Source Declaration from FieldContent.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 field
FieldDescriptionProps
Exported Source Declaration from FieldDescription.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 fields
FieldErrorProps
Exported Source Declaration from FieldError.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 field
FieldGroupProps
Exported Source Declaration from FieldGroup.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

Declaration
FieldLabelProps
Exported Source Declaration from FieldLabel.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

Declaration
FieldLegendProps
Exported Source Declaration from FieldLegend.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 field
FieldSeparatorProps
Exported Source Declaration from FieldSeparator.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

Declaration
FieldSetProps
Exported Source Declaration from FieldSet.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 field
FieldTitleProps
Exported Source Declaration from FieldTitle.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

Declaration
FieldRootVariants
Exported Source Declaration from field-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.

  1. Activate every visible field label and confirm it targets the intended control rather than another form instance.
  2. Inspect the actual input for required, disabled and invalid states; do not stop at wrapper data attributes.
  3. 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.

Take the Next Useful Step

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.