oks-ui

How to use

FormFieldSet

FormFieldSet is one component that dispatches to 12 different field implementations based on its type prop — text, number, email, password, select, radio, checkbox, switch, date picker, phone, file, and more — sharing one validation system and one Form context, so every field type is styled, labeled, and validated consistently without hand-building 12 separate wrappers.

import { Form, FormFieldSet } from "oks-ui";

One field, twelve types

type picks the field implementation; every other prop after that is shared (label, description, size, variant, color, labelPlacement) plus whichever props are specific to that type (options for select/radio/checkbox, length for otp, accept for file). FormFieldSet must live inside a Form for validation/submission to work — it registers itself with the nearest Form context on mount.

<Form onSubmit={(data) => console.log(data)}>
  <FormFieldSet type="text" name="name" label="Name" />
  <FormFieldSet type="email" name="email" label="Email" validation={{ rules: { required: true, email: true } }} />
  <FormFieldSet
    type="select"
    name="role"
    label="Role"
    options={[
      { label: "Admin", value: "admin" },
      { label: "Editor", value: "editor" },
      { label: "Viewer", value: "viewer" },
    ]}
  />
  <FormFieldSet type="switch" name="notifications" label="Email notifications" />
  <Button type="submit">Save</Button>
</Form>

Validation

validation.rules covers the common cases declaratively — required, email, minLength/maxLength, min/max, pattern, and a custom function rule for anything bespoke. Errors are computed by Form and shown per-field automatically once a field is touched (or immediately, depending on Form's showErrorsOn setting).

<FormFieldSet
  type="password"
  name="password"
  label="Password"
  validation={{
    rules: {
      required: true,
      minLength: 8,
      custom: (value) => /[A-Z]/.test(String(value)) || "Needs at least one uppercase letter",
    },
  }}
/>

Controlled and uncontrolled

Every field type works both ways: pass value + onChange for a fully controlled field, or defaultValue and let Form track the value internally through its own formData state — the same convention across all 12 types, so switching a field between controlled and uncontrolled doesn't change how you read its value elsewhere (Form's formData always reflects the current value either way).

Label placement

labelPlacement controls where the label sits relative to the control — top (the default), left, right, or floating (the label starts inside the control and animates up once it has a value or focus). All 12 field types support the full set.

<FormFieldSet type="text" name="company" label="Company" labelPlacement="floating" />
<FormFieldSet type="text" name="role" label="Role" labelPlacement="left" />

Repeating fields with LoopFields

For a variable-length group of fields (a list of email addresses, multiple phone numbers), LoopFields handles the add/remove/reindex bookkeeping — each item gets a stable identity across removals so validation state and values stay attached to the right item, not just the right position.

<LoopFields name="emails" minItems={1}>
  {({ index, name }) => (
    <FormFieldSet type="email" name={`${name}`} label={`Email ${index + 1}`} />
  )}
</LoopFields>

Accessibility

  • Every field type renders a real, correctly-associated <label> (or aria-label for labelPlacement="floating" edge cases) tied to its control via htmlFor/id, generated automatically when you don't pass an explicit id.
  • Validation errors render with role="alert" and are linked to their field via aria-describedby, so a screen reader announces the error in context with the field it belongs to.
  • labelPlacement="floating" keeps a real, associated label at all times — it's a visual animation, not a placeholder-only pattern that would leave the field unlabeled once the placeholder text disappears.

Props reference

All available props for FormFieldSet. See the full component page for an interactive playground.

Props

onChange

(files: File[]) => void

Default: —

Called with the resolved list of selected files.

onClear

() => void

Default: —

Called when cleared.

Best practices

  • Group related fields under one Form even when you only care about validating a subset at a time (as SteppedForm does internally) — Form's full-schema validation on submit is what catches anything missed by earlier per-step or per-field checks.
  • Prefer declarative validation.rules over a custom function whenever the built-in rules cover the case — they're what Form's error-timing logic (showErrorsOn, validateOnMount) is built around, and stay consistent across every field type.
  • Use LoopFields instead of manually managing an array of FormFieldSets in your own state — the reindexing-on-removal behavior is easy to get subtly wrong by hand (stale keys, misattributed errors after a middle item is removed).
  • Match labelPlacement to information density: "top" for typical forms, "left"/"right" for compact settings-style rows, "floating" for a tighter visual footprint where a persistent top label would waste vertical space.
View full API reference for FormFieldSet →