formsform-field

FormField

Form field wrapper providing label, description, and validation message layout.

Import#

import { createForm, Form, FormField } from 'moraine'

Inside Form, a named field automatically reads its value and validation state from Formisch. Top-level fields accept a string name; nested and array fields use a path such as ['users', 0, 'email']. Outside Form, the component remains a standalone layout primitive.

Pass the schema type to validate names at compile time:

<FormField<typeof schema> name={['profile', 'email']} label="Email">
  <Input />
</FormField>

Slot Structure#

Label, description, and hint area above a control slot with validation feedback.

root
├── wrapper
│   ├── labelWrapper (optional)
│   │   ├── label
│   │   └── hint (optional)
│   └── description (optional)
└── {children}
    ├── help (optional)
    └── error (optional)

Examples#

Basic#

Label, hint, description, and help text with a single control.

1
function Basic() {
2
  return (
3
    <div class="mx-auto max-w-xl w-full">
4
      <FormField
5
        label="Workspace Name"
6
        hint="Required"
7
        description="Name used in URLs and workspace-level permissions."
8
        help="Use lowercase letters, numbers, and dashes."
9
        required
10
      >
11
        <Input placeholder="acme-platform" />
12
      </FormField>
13
    </div>
14
  )
15
}

With Validation#

Bind to a Formisch store and show validation feedback without a render prop.

1
function WithValidation() {
2
  const form = createForm({
3
    schema: v.object({ email: v.pipe(v.string(), v.email('Enter a valid email.')) }),
4
    initialInput: { email: '' },
5
  })
6

7
  return (
8
    <Form of={form} class="mx-auto max-w-xl w-full space-y-4">
9
      <FormField name="email" label="Owner Email" required>
10
        <Input type="email" placeholder="[email protected]" />
11
      </FormField>
12

13
      <Button type="submit">Save</Button>
14
    </Form>
15
  )
16
}

Horizontal Layout#

Use orientation="horizontal" for form-like row layouts.

1
function HorizontalLayout() {
2
  return (
3
    <div class="mx-auto max-w-2xl w-full space-y-4">
4
      <FormField
5
        orientation="horizontal"
6
        label="Display Name"
7
        description="Public name shown in activity feeds."
8
      >
9
        <Input placeholder="Moraine Team" />
10
      </FormField>
11

12
      <FormField orientation="horizontal" label="Default Role" required>
13
        <Select
14
          options={[
15
            { label: 'Developer', value: 'developer' },
16
            { label: 'Designer', value: 'designer' },
17
            { label: 'Manager', value: 'manager' },
18
          ]}
19
          placeholder="Select role"
20
        />
21
      </FormField>
22
    </div>
23
  )
24
}

Sizes#

Preview the field typography scale from xs to xl.

1
function Sizes() {
2
  const SIZES: FormFieldSizeName[] = ['xs', 'sm', 'md', 'lg', 'xl']
3

4
  type FormFieldSizeName = Exclude<FormFieldT.Variant['size'], undefined>
5

6
  return (
7
    <div class="gap-4 grid sm:grid-cols-2">
8
      <For each={SIZES}>
9
        {(size) => (
10
          <FormField
11
            size={size}
12
            label={`Workspace Name (${size})`}
13
            description="Name used in URLs and workspace-level permissions."
14
            help="Use lowercase letters, numbers, and dashes."
15
          >
16
            <Input size={size} placeholder={`acme-platform-${size}`} />
17
          </FormField>
18
        )}
19
      </For>
20
    </div>
21
  )
22
}

Manual Error#

Force error state with a custom error message.

1
function ManualError() {
2
  return (
3
    <div class="mx-auto max-w-xl w-full">
4
      <FormField
5
        label="Access Token"
6
        hint="Required"
7
        error="Token has expired. Generate a new token and retry."
8
      >
9
        <Input type="password" value="********" />
10
      </FormField>
11
    </div>
12
  )
13
}

Render Context#

Use render-function children to react to error state.

1
function RenderContext() {
2
  const form = createForm({
3
    schema: v.object({
4
      releaseTitle: v.pipe(v.string(), v.nonEmpty('Release title is required.')),
5
    }),
6
    initialInput: { releaseTitle: '' },
7
  })
8

9
  return (
10
    <Form of={form} class="mx-auto max-w-xl w-full space-y-4">
11
      <FormField name="releaseTitle" label="Release Title" required>
12
        {(props) => <Input placeholder={props.error ? 'Title is required' : 'v2.14.0'} />}
13
      </FormField>
14

15
      <Button type="submit">Create Draft</Button>
16
    </Form>
17
  )
18
}

Nested Path#

Use array path names for nested form fields.

1
function NestedPath() {
2
  const form = createForm({
3
    schema: v.object({
4
      profile: v.object({
5
        name: v.pipe(v.string(), v.nonEmpty('Name is required.')),
6
        email: v.pipe(v.string(), v.email('Valid email is required.')),
7
      }),
8
    }),
9
    initialInput: { profile: { name: '', email: '' } },
10
  })
11

12
  return (
13
    <Form of={form} class="mx-auto max-w-xl w-full space-y-4">
14
      <FormField name={['profile', 'name']} label="Profile Name" required>
15
        <Input placeholder="Moraine Team" />
16
      </FormField>
17

18
      <FormField name={['profile', 'email']} label="Profile Email" required>
19
        <Input type="email" placeholder="[email protected]" />
20
      </FormField>
21

22
      <Button type="submit">Save Profile</Button>
23
    </Form>
24
  )
25
}

API Reference#

Attributes#

Slotroot1 attribute

Field wrapper that links label, control, description, and messages.

Data Attributes

Data Attribute	Description
data-orientation	Stores the rendered orientation.

Props#

Prop	Type	Default	Description
as	`T \| undefined`	`div`	The HTML element or component to render as.
children	`ComponentOrElement<FormFieldT.RenderContext> \| undefined`	—	Children of the field, can be a render function.
class	`ClassValue`	—	Class applied to the component root or trigger element.
classes	`FormFieldT.Classes \| undefined`	—	—
description	`JSX.Element`	—	Description text shown below the label.
error	`boolean \| string \| JSX.Element`	—	Custom error message or force error state.
help	`JSX.Element`	—	Help text shown below the control when no error is present.
hint	`JSX.Element`	—	Hint text shown near the label.
id	`string \| undefined`	—	Unique identifier for the form field.
label	`JSX.Element`	—	Label for the field.
name	`FormFieldT.Name<TSchema> \| undefined`	—	The name of the field (key in form state).
orientation	`"horizontal" \| "vertical" \| undefined`	—	—
ref	`JSX.HTMLElementTags[T] extends { ref?: infer Ref; } ? Ref : never \| undefined`	—	—
required	`boolean \| undefined`	`false`	Whether the field is required.
size	`"xs" \| "sm" \| "md" \| "lg" \| "xl" \| undefined`	—	—
style	`JSX.CSSProperties \| undefined`	—	—
styles	`FormFieldT.Styles \| undefined`	—	—