Build faster with Premium Chakra UI Components 💎

Learn more
Skip to Content
DocsShowcaseBlogGuides
Sponsor

Field

Used to add labels, help text, and error messages to form fields.

SourceStorybookRecipeArk
AI TipWant to skip the docs? Use the MCP Server

Usage

import { Field } from "@chakra-ui/react"
<Field.Root>
  <Field.Label>
    <Field.RequiredIndicator />
  </Field.Label>
  <Input />
  <Field.HelperText />
  <Field.ErrorText />
</Field.Root>
info
If you prefer a closed component composition, check out the snippet below.

Examples

Error Text

Pass the invalid prop to Field.Root and use the Field.ErrorText to indicate that the field is invalid.

This is an error text

Helper Text

Use the Field.HelperText to add helper text to the field.

This is a helper text

Horizontal

Use the orientation="horizontal" prop to align the label and input horizontally.

Disabled

Use the disabled prop to disable the field.

Textarea

Here's how to use the field component with a textarea.

Native Select

Here's how to use the field component with a native select.

Required

Pass the required prop to Field.Root and use the Field.RequiredIndicator to indicate that the field is required.

Optional

Pass the fallback prop to the Field.RequiredIndicator to add optional text.

Closed Component

Here's how to setup the Field for a closed component composition.

import { Field as ChakraField } from "@chakra-ui/react"
import * as React from "react"

export interface FieldProps extends Omit<ChakraField.RootProps, "label"> {
  label?: React.ReactNode
  helperText?: React.ReactNode
  errorText?: React.ReactNode
  optionalText?: React.ReactNode
}

export const Field = React.forwardRef<HTMLDivElement, FieldProps>(
  function Field(props, ref) {
    const { label, children, helperText, errorText, optionalText, ...rest } =
      props
    return (
      <ChakraField.Root ref={ref} {...rest}>
        {label && (
          <ChakraField.Label>
            {label}
            <ChakraField.RequiredIndicator fallback={optionalText} />
          </ChakraField.Label>
        )}
        {children}
        {helperText && (
          <ChakraField.HelperText>{helperText}</ChakraField.HelperText>
        )}
        {errorText && (
          <ChakraField.ErrorText>{errorText}</ChakraField.ErrorText>
        )}
      </ChakraField.Root>
    )
  },
)

If you want to automatically add the closed component to your project, run the command:

npx @chakra-ui/cli snippet add field

Props

Root

PropDefaultType
colorPalette gray
'gray' | 'red' | 'orange' | 'yellow' | 'green' | 'teal' | 'blue' | 'cyan' | 'purple' | 'pink'

The color palette of the component

orientation vertical
'vertical' | 'horizontal'

The orientation of the component

as
React.ElementType

The underlying element to render.

asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
unstyled
boolean

Whether to remove the component's style.

disabled
boolean

Indicates whether the field is disabled.

ids
ElementIds

The ids of the field parts.

invalid
boolean

Indicates whether the field is invalid.

readOnly
boolean

Indicates whether the field is read-only.

required
boolean

Indicates whether the field is required.

Explorer

Explore the Field component parts interactively. Click on parts in the sidebar to highlight them in the preview.

Enter your email. We’ll never share it.Please enter a valid email
Optional: You can leave this empty

Component Anatomy

Hover to highlight, click to select parts

root

errorText

helperText

input

label

select

textarea

requiredIndicator

field.recipe.ts

Previous

Editable

Next

Fieldset