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 Library

Forms that Guide People from Input to Completion

Build forms with Clear Labels, Useful Validation and Predictable Submission. Combine Kamod’s Preact controls with native form semantics, then add a schema and coordinated state when the task needs them. Your application supplies the service calls and business rules; the interface should make every step understandable.

Start with a small working form, explore the Formisch Integration for @formisch/preact and valibot, and keep field styling aligned with the Shared CSS Foundation. The guidance below covers Field Choice, State, Errors and Recovery, with copyable examples and checks for real content, keyboard use and both color schemes.

New to the library? The Getting Started Guide connects forms to the shared setup and your first working screen. For stylesheet setup, see the CSS Guide.


Find Your Form Starting Point

Start with the Simplest Form that Meets the Task. Native controls may be enough for a short form. Introduce Formisch when shared validation rules, coordinated field state or repeatable groups become useful. The integration works with your Preact app and existing Kamod styling.

Keep your current form library if it already meets those needs. You can compare Native, Schema and Formisch Examples on this page before choosing how much coordination to add.

Define Shared Rules with a Schema

Start with the values the task actually needs. A Valibot schema describes their shape and validation messages; useForm connects those rules to initial values and field state. Keep One Source of Truth for the rules instead of repeating them in every control.

Install @formisch/preact and valibot, then choose when to validate: on submission, on blur or while editing.

Connect State to Familiar Controls

Keep your Kamod components and theme. Connect field.props to an Input, give it a visible Label, and place its feedback nearby. Formisch coordinates the value and errors; your layout makes them understandable.

For composite controls such as Select, connect the value callback to field.onChange. Avoid Mirroring Field Values in a second useState; two competing values make reset and validation harder to follow.

Carry Submission through to Recovery

Connect validated output to your application’s save operation through onSubmit. Return or await asynchronous work so the form can track submission. Give the Button a clear pending state and prevent duplicate requests while saving.

Keep Field Errors and Service Failures distinct. A failed request should leave entered values available for another attempt. Add repeatable fields only when the task needs them, keeping labels and errors connected as items are added or removed.

Design the Task before the Fields

Ask for the Smallest Set of Information that Completes the Task. Give the form a Clear Purpose and make its Button describe the result—“Save Profile” or “Send Request.” A short profile update and a multi-step application have different needs; collect only the values the application will use. Start with a Working Example, then choose the controls below.

Group Related Choices in a Predictable Order. Keep Labels and Instructions close to their inputs, explain unfamiliar requirements before entry, and mark optional fields consistently. Use required when an answer is necessary, then plan When to Validate and How to Explain Errors before connecting submission. The Submission and Recovery Guide covers what happens next.

The InputInput & ControlStart WithDesign Detail
A short answerInputSingle-line valueInputSingle-line valueChoose the right type and autoComplete hint. Keep a Visible Label after the person starts typing.
A longer answerTextareaMulti-line textTextareaMulti-line textExplain Length Requirements before submission. Set appropriate rows and leave room to review what was written.
One choiceRadioGroupOne value from a setRadioGroupOne value from a setShow a short set of meaningful options together. For a longer list, consider Select or NativeSelect.
Independent choicesCheckboxSeparate selectionsCheckboxSeparate selectionsUse Separate Values for choices that can be combined. Explain whether at least one selection is required and when Validation Runs.
An on/off preferenceSwitchBoolean settingSwitchBoolean settingClarify whether the change applies Immediately or needs Save. Keep the Saving Behavior consistent throughout the form.
Related fieldsFieldLabel, help and errorFieldLabel, help and errorKeep labels, descriptions and errors with the control. Use a fieldset and legend for a Named Group.

Keep the Structure Native

Start with a native Form, a Visible Label, a named input and a submit button. The browser already understands keyboard submission, required fields and many common input types. Kamod’s Input, Label and Button let you retain those semantics while using your app’s theme.

Give every submitted control a name. Match htmlFor to a unique id, connect helper text with aria-describedby, and use Explicit Button Types. A secondary action inside a form should usually be type="button"; use type="reset" only when clearing the form is intentional and understandable.

Prefer a Single Column on small screens. Two fields can share a row when their relationship is clear, but the reading and keyboard order should remain predictable. Long error messages must wrap without pushing controls beyond the screen edge. Use the Form Review Checklist to check keyboard order, focus and narrow layouts.

Build from a Small, Working Example

These examples assume your Preact app already has Kamod UI and its styles configured. Start with the native version, introduce a schema when rules need to be reused, then use Formisch for Coordinated Values, Validation and Submission. The schema and Formisch examples additionally require valibot and @formisch/preact; follow the Formisch Installation Guide.

The preview is a safe place to try empty input, an invalid email and a successful check. It Does Not Save Data or Contact a Service. Copy the source into your own project and supply the application callback when you are ready to integrate it.

Start with the Browser’s Form Semantics

A visible label, a named field and a submit button are enough for a small form. Native required and email validation run before the submit handler. The callback below belongs to your application; the live demo only checks the form locally.

Try a sample address. This demo sends and saves nothing.

Ready to check your input.

src/components/EmailForm.tsx17 lines
import { Button, Input, Label } from "@kamod-ch/ui";

export function EmailForm({ onSave }: { onSave: (email: string) => void }) {
  return (
    <form class="grid gap-3" onSubmit={(event) => {
      event.preventDefault();
      const data = new FormData(event.currentTarget);
      onSave(String(data.get("email") ?? ""));
    }}>
      <Label htmlFor="contact-email">Email address</Label>
      <Input id="contact-email" name="email" type="email"
        autoComplete="email" required aria-describedby="email-help" />
      <p id="email-help">Use the address where we can reach you.</p>
      <Button type="submit">Save email</Button>
    </form>
  );
}

Start with the Browser, Then Connect Your App

Keep the first form small: a Visible Label, a named input and a clear action. Let native checks handle missing or malformed values before you add your own Submission Behavior.

Make the Input Easy to Understand

Before submission

Keep the label visible while typing and connect it with matching htmlFor and id values. Use required and type="email" to let the browser explain missing or malformed input. Try both cases before connecting a service.

Follow the Value into Your Handler

On submit

Enter reader@example.com and press Enter. In the copied example, FormData reads the input’s name="email" and passes the value to onSave. The live preview only confirms validity; it does not send or store data.

Keep the Form Usable as It Grows

When integrating

Give repeated form instances unique input and help-text IDs. Once saving becomes asynchronous, show a Pending State and keep the entered value if the request fails. The Review Checklist covers keyboard order, focus and recovery.

Make Validation Understandable

Choose When Feedback Appears

For many forms, validating on submit avoids showing errors before someone has had a chance to answer. After an error appears, revalidating while editing helps people see when they have fixed it. Validation on blur can suit longer forms, but it should not interrupt the flow of entering a value.

Formisch exposes validate and revalidate settings. Choose them deliberately for the task, and avoid duplicate custom validation paths that disagree with the schema. If you turn off browser validation with noValidate, make sure the form library provides the complete feedback path instead.

Explain the Fix, Not Just the Failure

“Enter a valid email address” Is Useful; “Invalid input” Is Not Enough.Describe the requirement in plain language, retain what was entered and associate the message with its field. Pair an error color with text and aria-invalid; color alone does not explain what happened.

For several errors, an error summary can point to the affected fields. Decide where focus should go after submission and check that the first invalid field is reachable. Avoid repeatedly moving focus while someone is typing or announcing every keystroke.

Client rules are a convenience, not an authorization boundary. Validate again on the server and return errors that the form can map to a field or a general message. Treat a conflict, an expired session and a network failure as different situations when their recovery steps differ.

Connect Submission and Recovery

Separate Editing, Saving and Saved State

Keep the current field values separate from the last confirmed result. When saving starts, show a concise pending label and prevent duplicate submissions. Await the Actual Operation before showing success. A resolved client handler does not mean the server accepted the change unless your integration checks the response.

Let the owning page supply the request, authentication and routing. A reusable form should accept a callback rather than hard-code an endpoint. Return its promise to the form library so pending state follows the work, and translate a rejected request into a useful message.

Keep a Path Back to Progress

On failure, keep useful input and make retry possible. On success, decide whether the form stays open, resets or navigates away; show what happened before removing the context. An optimistic update needs a defined rollback path if the request fails.

For dynamic fields, use stable keys and meaningful labels. A removed row should not make keyboard focus disappear. For custom Select, Checkbox or Switch controls, connect the documented value/change props to Formisch explicitly. Use the Full Integration Examples for field arrays, reset behavior and supported control adapters.

Make It Your Own

Set Up Once, Reuse Everywhere. These guides apply to individual components and complete blocks. Start with the global stylesheet and Tailwind CSS source detection, then choose your theme and finish with consistent icons. Following this order makes it easier to tell a setup issue from a change you want to make to the design.

Keep your app’s existing conventions and connect the shared foundation before overriding local classes. Each guide below focuses on one part of that setup and includes a quick visual check. Once the basics look right, use real content to review spacing, contrast and keyboard behavior in both light and dark modes.

Before you ship
Make the content yours

Check in Your App. Try real content, a narrow viewport and keyboard navigation before shipping. Use the Theme Guide to check both light and dark appearances. Replace sample routes and service callbacks with your own, then check empty states and longer labels. Keep the Shared Behavior; Make the Content Yours.

Work with the Source

A Useful Next Step: Read the Piece You Want to Change. These two repositories cover the components and visual details behind the library. Check the README and the version in your package.json when comparing an example with your installed API.

Review Every Path through the Form

Test the complete task with Realistic Input and Service Responses. A form that looks correct with one valid value may still be difficult to use when data is missing, a request is slow or a label is translated.

  • Keyboard and Labels. Tab through every control, submit with Enter where appropriate, and verify focus after errors, reset and dynamic field changes. Check that every control has an accessible name.
  • Boundaries. Try empty input, surrounding whitespace, long text and values at each minimum or maximum. Verify that the server and client rules agree.
  • Request States. Simulate pending, success, validation failure, offline behavior and retry. Confirm repeated clicks cannot trigger duplicate writes.
  • Presentation. Check both color modes, enlarged text and narrow screens. Error text should wrap, the primary action should stay reachable and focus should remain visible.
  • Production. Run the relevant tests and build from package.json. Open the form route directly in the production output and verify styles, initial values and any restored draft behavior.

Keep a small regression test for the most important success and failure paths. If a pattern repeats, extract the field composition or submit adapter after its behavior is clear. Reuse the Interaction, Not Just the Appearance.

A useful next step

Build One Complete Form, from Input to Recovery

Follow the Formisch guide for schema-backed fields and examples. Connect a real submission handler, keep errors understandable and verify keyboard navigation before shipping.

Explore Formisch

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 Connect Fields, Validation and Submission 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.