On this page

Field

A wrapper component that adds label, helper text, and error text to form inputs.

import { Field } from "@ninna-ui/forms";

pnpm add @ninna-ui/forms@latest

Includes @ninna-ui/core. CSS setup required.View source

Usage

Import and use the Field component to wrap inputs with labels and helper text.

import { Field, Input } from "@ninna-ui/forms";

export default function Example() {
  return (
    <Field label="Email" helperText="We'll never share your email">
      <Input placeholder="Enter your email" />
    </Field>
  );
}

Basic

Basic field with a label.

Live preview/ Default

Helper Text

Field with helper text below the input.

Live preview/ Default

We'll never share your email with anyone.

Error Text

Field in an invalid state with error message.

Live preview/ Default

Password

Password must be at least 8 characters

Required

Field marked as required.

Live preview/ Default

Username*

Optional Text

Field with optional indicator.

Live preview/ Default

BioOptional

All Props

Field with various prop combinations: disabled, sizes, optionalText.

Live preview/ Default

With optional textOptional

Disabled field

Small size

Large size

Field as Primary Wrapper

Comprehensive guide showing Field as the recommended pattern for wrapping form inputs with React Hook Form integration.

Live preview/ Default

Field as Primary Wrapper Pattern

The Field component is the recommended way to wrap form inputs. It provides:

Labels - Properly associated with inputs via htmlFor
Helper text - Guidance linked via aria-describedby
Error messages - With role="alert" for accessibility
Required/Optional indicators - Visual and semantic
Consistent spacing - Uniform form layout

Integration Patterns

Native inputs (Input, Textarea):

<Field label="Email" errorText={errors.email?.message}>
  <Input {...register('email')} />
</Field>

Controlled components (Select, Checkbox, Switch, Slider):

<Field label="Country" errorText={errors.country?.message}>
  <Controller
    name="country"
    control={control}
    render={({ field }) => (
      <Select value={field.value} onValueChange={field.onChange}>
        ...
      </Select>
    )}
  />
</Field>

API Reference

Complete list of props for the Field component.

Props

Prop	Type	Default	Description
`label`	`string`	`—`	Label text
`helperText`	`string`	`—`	Helper text displayed below the input
`errorText`	`string`	`—`	Error text displayed when invalid
`required`	`boolean`	`false`	Whether the field is required
`invalid`	`boolean`	`false`	Whether the field is invalid
`disabled`	`boolean`	`false`	Whether the field is disabled
`size`	`'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'`	`'md'`	Size of the field elements
`optionalText`	`string`	`—`	Text displayed on the right side of the label
`children`*	`ReactNode`	`—`	Input component to wrap
`id`	`string`	`—`	ID for the field (used to link label with input)

Accessibility

Label is properly associated with input via htmlFor
Helper/error text linked via aria-describedby
Required fields have aria-required attribute
Invalid fields have aria-invalid attribute
Error messages use role="alert" for screen readers
Supports all native div ARIA attributes via props spread