React FormField: examples and API

Preview

Live preview

Changes apply to this preview only.

Display name

Shown on your public profile.

This address is already in use.

Social

Optional links.

GitHub

Website

BioOptional

Width adapts to the available space

"use client";

import {
  Card,
  CardHeader,
  CardTitle,
  CardDescription,
  CardContent,
  FormField,
  FormControl,
  Input,
  FormGroup,
  Textarea,
  Button
} from "@pimolu/react";

export function DemoExample() {
  return (
    <Card>
      <CardHeader>
        <CardTitle>Profile</CardTitle>
        <CardDescription>
          A complete form: required fields, a helper, an error, a grouped
          pair and an action.
        </CardDescription>
      </CardHeader>
      <CardContent>
        <div className="grid gap-5 min-w-0">
          <FormField
            label="Display name"
            required
            helperText="Shown on your public profile."
          >
            <FormControl>
              <Input defaultValue="Ada Lovelace" />
            </FormControl>
          </FormField>
          <FormField
            label="Email"
            required
            errorMessage="This address is already in use."
          >
            <FormControl>
              <Input type="email" defaultValue="ada@example.com" invalid />
            </FormControl>
          </FormField>
          <FormGroup
            label="Social"
            description="Optional links."
            orientation="horizontal"
          >
            <FormField label="GitHub">
              <FormControl>
                <Input placeholder="ada" />
              </FormControl>
            </FormField>
            <FormField label="Website">
              <FormControl>
                <Input placeholder="https://" />
              </FormControl>
            </FormField>
          </FormGroup>
          <FormField label="Bio" optional optionalLabel="Optional">
            <FormControl>
              <Textarea rows={3} placeholder="A short introduction" />
            </FormControl>
          </FormField>
          <div className="flex flex-wrap items-center gap-3 min-w-0">
            <Button>Save profile</Button>
            <Button appearance="ghost">Cancel</Button>
          </div>
        </div>
      </CardContent>
    </Card>
  );
}

More examples

Different configurations and compositions using the real Pimolu API. Each preview runs independently and follows the site appearance.

Field

The label, the control and the message are wired together: htmlFor, id, aria-describedby and aria-invalid.

Open preview

Error and optional

errorMessage replaces helperText, marks the control invalid and is announced as an alert.

Open preview

Message

FormMessage also works on its own for a short hint or an error.

Open preview

Usage

Connect the field's id to its label and descriptive feedback rather than duplicating labels.

API reference

Generated from the public TypeScript declarations. Native HTML attributes are inherited where the component extends them; this reference includes Pimolu props and selected common native attributes.

PimoluFormFieldProps

Type source

PimoluFormFieldProps public API
Name	Type	Default	Description
`children`Required	`ReactNode`	—	The control, usually wrapped in FormControl.
`label`	`ReactNode`	—	Visible label.
`id`	`string \| undefined`	—	Explicit id of the control; generated when omitted.
`helperText`	`ReactNode`	—	Supporting text below the control.
`errorMessage`	`ReactNode`	—	Error text; takes precedence over helperText.
`required`	`boolean \| undefined`	`false`	Marks the control and its label as required.
`optional`	`boolean \| undefined`	`false`	Shows the optional hint after the label.
`optionalLabel`	`string \| undefined`	`"Optional"`	Text of the optional hint. Defaults to "Optional".
`invalid`	`boolean \| undefined`	`false`	Invalid state without a message.
`disabled`	`boolean \| undefined`	`false`	Disable the field and its label.
`className`	`string \| undefined`	—	Public Pimolu prop; see the source declaration for details.

childrenRequired: ReactNode
No default extracted.
The control, usually wrapped in FormControl.
label: ReactNode
No default extracted.
Visible label.
id: string | undefined
No default extracted.
Explicit id of the control; generated when omitted.
helperText: ReactNode
No default extracted.
Supporting text below the control.
errorMessage: ReactNode
No default extracted.
Error text; takes precedence over helperText.
required: boolean | undefined
Default: false
Marks the control and its label as required.
optional: boolean | undefined
Default: false
Shows the optional hint after the label.
optionalLabel: string | undefined
Default: "Optional"
Text of the optional hint. Defaults to "Optional".
invalid: boolean | undefined
Default: false
Invalid state without a message.
disabled: boolean | undefined
Default: false
Disable the field and its label.
className: string | undefined
No default extracted.
Public Pimolu prop; see the source declaration for details.

PimoluFormControlProps

Type source

PimoluFormControlProps public API
Name	Type	Default	Description
`children`Required	`ReactElement<unknown, string \| JSXElementConstructor<any>>`	—	A single form control. It receives the generated id, aria-describedby, aria-invalid, required and disabled from the surrounding FormField.

childrenRequired: ReactElement<unknown, string | JSXElementConstructor<any>>
No default extracted.
A single form control. It receives the generated id, aria-describedby, aria-invalid, required and disabled from the surrounding FormField.

PimoluFormMessageProps

Type source

PimoluFormMessageProps public API
Name	Type	Default	Description
`children`	`ReactNode`	—	Public Pimolu prop; see the source declaration for details.
`variant`	`"helper" \| "error" \| undefined`	`"helper"`	Helper text or an error. Defaults to "helper".
`id`	`string \| undefined`	—	Explicit id, for aria-describedby.
`className`	`string \| undefined`	—	Public Pimolu prop; see the source declaration for details.

children: ReactNode
No default extracted.
Public Pimolu prop; see the source declaration for details.
variant: "helper" | "error" | undefined
Default: "helper"
Helper text or an error. Defaults to "helper".
id: string | undefined
No default extracted.
Explicit id, for aria-describedby.
className: string | undefined
No default extracted.
Public Pimolu prop; see the source declaration for details.

PimoluFormGroupProps

Type source

PimoluFormGroupProps public API
Name	Type	Default	Description
`children`Required	`ReactNode`	—	Public Pimolu prop; see the source declaration for details.
`label`	`ReactNode`	—	Group heading.
`description`	`ReactNode`	—	Supporting text under the heading.
`orientation`	`"horizontal" \| "vertical" \| undefined`	`"vertical"`	Direction of the items. Defaults to "vertical".
`className`	`string \| undefined`	—	Public Pimolu prop; see the source declaration for details.

childrenRequired: ReactNode
No default extracted.
Public Pimolu prop; see the source declaration for details.
label: ReactNode
No default extracted.
Group heading.
description: ReactNode
No default extracted.
Supporting text under the heading.
orientation: "horizontal" | "vertical" | undefined
Default: "vertical"
Direction of the items. Defaults to "vertical".
className: string | undefined
No default extracted.
Public Pimolu prop; see the source declaration for details.

PimoluFieldsetProps

Type source

PimoluFieldsetProps public API
Name	Type	Default	Description
`children`Required	`ReactNode`	—	Public Pimolu prop; see the source declaration for details.
`legend`Required	`ReactNode`	—	Native legend of the fieldset.
`description`	`ReactNode`	—	Supporting text under the legend.
`disabled`	`boolean \| undefined`	`false`	Disable every control in the fieldset.
`className`	`string \| undefined`	—	Public Pimolu prop; see the source declaration for details.

childrenRequired: ReactNode
No default extracted.
Public Pimolu prop; see the source declaration for details.
legendRequired: ReactNode
No default extracted.
Native legend of the fieldset.
description: ReactNode
No default extracted.
Supporting text under the legend.
disabled: boolean | undefined
Default: false
Disable every control in the fieldset.
className: string | undefined
No default extracted.
Public Pimolu prop; see the source declaration for details.

Accessibility

Keep help and errors associated with the input and explain errors in text.

Read the accessibility guide →

Preview

Profile

More examples

Field

Error and optional

Message

Usage

API reference

PimoluFormFieldProps

PimoluFormControlProps

PimoluFormMessageProps

PimoluFormGroupProps

PimoluFieldsetProps

Accessibility

Related components