The `<Field />` component is a composite wrapper component to help build forms more efficiently. It uses [React Context](https://reactjs.org/docs/context.html) to connect the label, description, and validation message to the input element.

For more realistic implementation examples in a form, see the [Forms pattern](/patterns/forms/examples/).

## Field vs Fieldset

Use `<Field />` when you are labelling one form control (for example a single text input or select). `Field` also includes built-in form UX like required indicators, error messages, and message spacing that matches other EDS form controls.

Use [Fieldset](/packages/fieldset/) when one label needs to describe multiple related controls (for example a radio group or a checkbox group). `Fieldset` gives you group semantics with `<fieldset>` and `<legend>`, and supports required group styling and state.

## Label

Fields must be accompanied by a label. Effective form labelling helps users understand what information to enter into an input.

```tsx live
<Field label="Name">
  <TextInput />
</Field>
```

### Label visibility

Some circumstances might omit the label from view where context is provided through positioning or other elements. You can use the `labelVisible` prop to achieve this. The label will still be attached to the input for assistive technologies, but visually hidden.

```tsx live
<Field label="Name" labelVisible={false}>
  <TextInput />
</Field>
```

## Description

Provides the user with a persistent message to assist in completing a field. This should be used where the information provided is highly pertinent.

```tsx live
<Field label="Email" description="We will only use this to respond to your question">
  <TextInput type="email" />
</Field>
```

## Required

Used to mark a field as mandatory to complete before submitting a form.

When building a form it's recommended to provide a legend above the fields which denotes the meaning of the \* symbol. NOTE: It is recommended to add `aria-hidden` on this text element, as screen readers will automatically announce "required" on the required fields.

```tsx live
<Flex flexDirection="column" gap="medium">
  <Text fontSize="small" aria-hidden>
    The fields marked with a <Text color="critical">*</Text> must be filled out before submitting this form.
  </Text>

  <Field required label="Email" description="We will only use this to respond to your question">
    <TextInput type="email" />
  </Field>
</Flex>
```

## Messages

Messages are used to notify the user about a form field's validation state. Typically this will be an error message, in which case use a clear message to explain what went wrong and how to fix it.

If `invalid` is true, the message will render in `critical` color, otherwise it defaults to `positive`. You can also use the `caution` prop to display a caution message in a `caution` color.

```tsx live
<Flex gap="large" flexDirection="column">
  <Field required label="Business name" invalid message="Please enter business name.">
    <TextInput />
  </Field>
  <Field label="Confirm new password" message="Password matched.">
    <TextInput value="1234567890" type="password" />
  </Field>
  <Field
    label="Base salary"
    caution
    message="Assigning the salary above will exceed the budgeted base salary for this position."
  >
    <TextInput type="number" value="100000" adornmentStart="$" />
  </Field>
</Flex>
```

### Keep space for message

By default, extra vertical space is kept under each field to prevent layout shifts when a validation message is displayed. You can turn this extra space off by setting `keepSpaceForMessage` to `false`.

```tsx live
const [keepSpace, setKeepSpace] = useState(true);
const [invalid, setInvalid] = useState(false);

return (
  <Flex flexDirection="column" gap="medium">
    <PlaygroundCard>
      <Flex gap="medium">
        <Toggle
          size="small"
          label="Keep space for message"
          onClick={() => setKeepSpace((prev) => !prev)}
          toggled={keepSpace}
        />
        <Toggle size="small" label="Fields are invalid" onClick={() => setInvalid((prev) => !prev)} toggled={invalid} />
      </Flex>
    </PlaygroundCard>

    <Flex flexDirection="column" gap={!keepSpace ? 'large' : undefined}>
      <Field label="Email" keepSpaceForMessage={keepSpace} invalid={invalid} message={invalid ? 'Invalid message' : ''}>
        <TextInput type="email" />
      </Field>

      <Field
        label="Password"
        keepSpaceForMessage={keepSpace}
        invalid={invalid}
        message={invalid ? 'Invalid message' : ''}
      >
        <TextInput type="password" />
      </Field>
    </Flex>
  </Flex>
);
```

## Field columns

When you need to position two fields next to each other (horizontally), you can use the `<FieldColumns />` component. This is merely a convenience wrapper around a `<Grid />`. It supports all the [`GridProps`](/packages/grid/props), but sets some responsive defaults to help implement this common layout:

- `gridTemplateColumns = { xsmall: '100%', small: 'repeat(2, 1fr)' }`
- `columnGap = 'medium'`
- `alignItems = 'end'` (for when the label of a Field wraps to multiple lines)

```tsx live
<FieldColumns>
  <Field label="Suburb">
    <TextInput />
  </Field>
  <Field label="Postcode">
    <TextInput />
  </Field>
</FieldColumns>
```

## Supported components

These components already support the `FieldContext` and can be used as children of a `<Field />`:

- [TextInput](/packages/text-input/)
- [TextAreaInput](/packages/text-area-input/)
- [SelectInput](/packages/select-input/)
- [SearchInput](/packages/search-input/)
- [PhoneInput](/packages/phone-input/)
- [FileInput](/packages/file-input/)
- [DateInput and DateRangeInput](/packages/date-input/)
- [AddressInput](/packages/address-input/)

Combines a label, description and message around an input element.

Field

Accessibility

Responsive layouts

Tokens

Foundations

a11y

Accordion

Actions

AddressInput

AppLayout

Avatar

Badge

Blanket

Breadcrumbs

BulkActionBar

Button

Card

Checkbox

Core

DateDropdown

DateInput

Divider

EmptyState

Fieldset

FileInput

Filtering

Flex

Grid

Heading

Icon

Illustration

Link

List

Loading

Modal

Notice

PageHeader

Pagination

PhoneInput

Popover

Radio

RailTrack

RichTextEditor

ScrollWrap

SearchInput

SelectDropdown

SelectInput

ShowMore

Table

Tabs

Text

TextAreaInput

TextInput

Toast

Toggle

Tooltip

Utils

Utils - NextJS

Components

Forms

Search

Tables

Patterns

Introduction

Product tone and voice

Capitalisation

Date and time

Inclusive design

Content

Welcome to EDS

Start designing

Start developing

Contributing

Releases

The EDS way

Coding style guide

Guide to Pendo

Setting up the EDS repo

Creating a new component

Automated testing

PR and changeset process

Publishing snapshots

Publishing packages

Monorepo tools

Team resources