Field

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

AI TipWant to skip the docs? Use the MCP Server

import { Field, Input } from "@chakra-ui/react"

const Demo = () => {
  return (
    <Field.Root>
      <Field.Label>Email</Field.Label>
      <Input placeholder="me@example.com" />
    </Field.Root>
  )
}

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.

EmailThis is an error text

import { Field, Input } from "@chakra-ui/react"

const Demo = () => {
  return (
    <Field.Root invalid>
      <Field.Label>Email</Field.Label>
      <Input placeholder="me@example.com" />
      <Field.ErrorText>This is an error text</Field.ErrorText>
    </Field.Root>
  )
}

Helper Text

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

EmailThis is a helper text

import { Field, Input } from "@chakra-ui/react"

const Demo = () => {
  return (
    <Field.Root>
      <Field.Label>Email</Field.Label>
      <Input placeholder="me@example.com" />
      <Field.HelperText>This is a helper text</Field.HelperText>
    </Field.Root>
  )
}

Horizontal

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

Name

Hide email

import { Field, Input, Stack, Switch } from "@chakra-ui/react"

const Demo = () => {
  return (
    <Stack gap="8" maxW="sm" css={{ "--field-label-width": "96px" }}>
      <Field.Root orientation="horizontal">
        <Field.Label>Name</Field.Label>
        <Input placeholder="John Doe" flex="1" />
      </Field.Root>

      <Field.Root orientation="horizontal">
        <Field.Label>Email</Field.Label>
        <Input placeholder="me@example.com" flex="1" />
      </Field.Root>

      <Field.Root orientation="horizontal">
        <Field.Label>Hide email</Field.Label>
        <Switch.Root>
          <Switch.HiddenInput />
          <Switch.Control />
        </Switch.Root>
      </Field.Root>
    </Stack>
  )
}

Disabled

Use the disabled prop to disable the field.

import { Field, Input } from "@chakra-ui/react"

const Demo = () => {
  return (
    <Field.Root disabled>
      <Field.Label>Email</Field.Label>
      <Input placeholder="me@example.com" />
    </Field.Root>
  )
}

Textarea

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

import { Field, Textarea } from "@chakra-ui/react"

const Demo = () => {
  return (
    <Field.Root>
      <Field.Label>Email</Field.Label>
      <Textarea placeholder="Email" />
    </Field.Root>
  )
}

Native Select

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

import { Field, NativeSelect } from "@chakra-ui/react"

const Demo = () => {
  return (
    <Field.Root>
      <Field.Label>Email</Field.Label>
      <NativeSelect.Root>
        <NativeSelect.Field>
          <option value="1">Option 1</option>
          <option value="2">Option 2</option>
          <option value="3">Option 3</option>
        </NativeSelect.Field>
        <NativeSelect.Indicator />
      </NativeSelect.Root>
    </Field.Root>
  )
}

Required

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

import { Field, Input } from "@chakra-ui/react"

const Demo = () => {
  return (
    <Field.Root required>
      <Field.Label>
        Email
        <Field.RequiredIndicator />
      </Field.Label>
      <Input placeholder="me@example.com" />
    </Field.Root>
  )
}

Optional

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

EmailOptional

import { Badge, Field, Input } from "@chakra-ui/react"

const Demo = () => {
  return (
    <Field.Root>
      <Field.Label>
        Email
        <Field.RequiredIndicator
          fallback={
            <Badge size="xs" variant="surface">
              Optional
            </Badge>
          }
        />
      </Field.Label>
      <Input placeholder="me@example.com" />
    </Field.Root>
  )
}

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

Prop	Default	Type
`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.

Email AddressEnter your email. We’ll never share it.Please enter a valid email

MessageOptional: 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

Editable

Fieldset

Field

.css-vfo6uh{color:var(--chakra-colors-fg);-webkit-text-decoration:underline;text-decoration:underline;text-underline-offset:3px;text-decoration-thickness:2px;text-decoration-color:var(--chakra-colors-border-emphasized);font-weight:500;}Usage

Component Anatomy

Usage