Alternatives

Fieldset — For grouping related form controls.

Field

Using context, the field component connects the label, description, and message to the input element.

<Field
  label="Field label"
  description="We will never share your information with third parties"
  message="This field is required"
>
  <TextInput />
</Field>

label

Each text field must be accompanied by a label. Effective form labeling helps users understand what information to enter into a text input.

Using placeholder text in lieu of a label is sometimes employed as a space-saving method. However, this is not recommended because it hides context and presents accessibility issues.

Edit in Playroom

<Field label="Name">
  <TextInput />
</Field>

labelVisible

There may be occasions where the label is apparent through context to sighted users, so you wish to omit it from the view. We still need a label attached to the input for assistive technology, in these cases you can provide the labelVisible property.

Edit in Playroom

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

description

Description text contains pertinent information that assists the user in completing a field. Description text is always visible and appears underneath the label. Use sentence-style capitalisation, and in most cases, write the text as full sentences with punctuation.

Edit in Playroom

<Field
  label="Email"
  description="We take your privacy seriously. We will never give your email to a third party."
>
  <TextInput />
</Field>

Link inside description text

You can pass a ReactElement as description. This should only be used when you need to put a link or some other interactive element in the description.

You don't need to concern yourself styling the text, it will be handled by the component. Just render your normal text inside a Fragment and use a TextLink component to render the link.

Note: Try not to make the description a complex component, it's supposed to support the user not overwhelm them.

Edit in Playroom

<Field
  label="Obscure field"
  description={
    <React.Fragment>
      This is a really obscure field. Learn more about it{' '}
      <TextLink href="#">here</TextLink>
    </React.Fragment>
  }
>
  <TextInput />
</Field>

helpText

Help text is hidden by default, and revealed in a tooltip invoked by an icon beside the label. Reserve help text for content only relevant during the first interaction a user has with the field. Use sentence-style capitalisation, and in most cases, write the text as full sentences with punctuation.

In most cases description is preferred.

Edit in Playroom

<Field
  label="Tax file number"
  helpText="TFN is an 8 or 9 digit number. If this employee has not provided one, we will set a default TFN. You may be asked to provide an updated TFN later."
>
  <TextInput placeholder="xxxxxxxxxx" />
</Field>

invalidMessage

Offer an invalid message to inform the user how their input violates the requirements of the field.

Edit in Playroom

<Field
  label="Invalid field"
  description="Passing an invalid message will automatically flag the the input as invalid"
  invalidMessage="Inform the user how their input violates the requirements of the field"
>
  <TextInput />
</Field>

reserveMessageSpace

Reserve the vertical space that will be taken by an invalid message. You would use this to stop subsequent elements from being pushed down when an invalid message is displayed.

Edit in Playroom

const [valid, setValid] = useState(true);
return (
  <Stack gap="medium">
    <Checkbox onChange={(e) => setValid(e.target.checked)} checked={valid}>
      <Text>Valid</Text>
    </Checkbox>
    <Field
      label="Reserve message space"
      reserveMessageSpace
      invalidMessage={valid ? null : 'Invalid message'}
    >
      <TextInput />
    </Field>
    <Text>Element to show document "reflow" when the message appears</Text>
  </Stack>
);

guidance

Field guidance is an extra information about the field. For example, it can be used to show remaining characters of the input field with maxLength property.

Edit in Playroom

const [value1, setValue1] = useState('');
const [value2, setValue2] = useState('');
const remainingCharactersGuidanceElement1 = useRemainingCharactersGuidance({
  maxLength: 5,
  currentValueLength: String(value1).length,
});
const remainingCharactersGuidanceElement2 = useRemainingCharactersGuidance({
  maxLength: 5,
  currentValueLength: String(value2).length,
});
return (
  <Stack gap="medium">
    <Field
      label="Field guidance"
      guidance={remainingCharactersGuidanceElement1}
    >
      <Textarea
        maxLength={5}
        value={value1}
        onChange={(e) => {
          setValue1(e.target.value);
        }}
      />
    </Field>
    <Field
      label="Field guidance with validation error"
      invalidMessage="Some validation error"
      guidance={remainingCharactersGuidanceElement2}
    >
      <Textarea
        maxLength={5}
        value={value2}
        onChange={(e) => {
          setValue2(e.target.value);
        }}
      />
    </Field>
  </Stack>
);

layout

Decides if the label and input should be laid out horizontally or vertically.

When horizontal, the component will try to fill all horizontal space via flex: 1.

Default value is vertical

Edit in Playroom

return (
  <Stack gap="medium">
    <Field label="Reserve message space" layout="horizontal">
      <TextInput />
    </Field>
    <Field
      label="Reserve message space"
      helpText="Help text"
      description="Description text"
      invalidMessage="Invalid message"
      layout="horizontal"
    >
      <TextInput />
    </Field>
  </Stack>
);

Testing

The field component generates testids automatically based on their field id. You can override this by providing a data attribute with a custom testid field.

Public Composition

Within the <Field>, the component sets a data-testid attribute on the root element and other public composable components will derive their own testids from it.

For more information on how to use the data attribute, see
Core documentation.
Utils documentation.

Edit in Playroom

<Field label="My field" data={{ testid: 'my-field' }}>
  <TextInput />
</Field>

This ends up generating the following testids:

my-field-1 - Main wrapper element
my-field-input-1 - Text input field
my-field-label-1 - Label element
my-field-description-1 - Description element
my-field-message-1 - Message element
my-field-help-indicator-1 - Help text tooltip element

Each component also provides a data-balance-component attribute. These are :

data-balance-component="field" - Main wrapper element
data-balance-component="field-input" - Text input field
data-balance-component="field-label" - Label element
data-balance-component="field-description" - Description element
data-balance-component="field-message" - Message element
data-balance-component="field-help-indicator" - Help text tooltip element

Private Composition

If you choose to provide your own instance of <FieldDescription>, <FieldMessage> or <HelpIndicator> inside your <Field> as children, then these will you will need to provide the testid to these yourself.

Without providing a data attribute, the component will not generate testids for these elements.

Edit in Playroom

<Field id="my-field" label="My field 1">
  <FieldDescription>This is a description</FieldDescription>
  <HelpIndicator>Help text</HelpIndicator>
  <TextInput />
  <FieldMessage>This is a message</FieldMessage>
</Field>

When you provide your own instances of these components, you can still use the data attribute to generate testids for them. This is useful for testing purposes.

Edit in Playroom

<Field data={{ testid: 'my-field-2' }}>
  <FieldDescription data={{ testid: 'my-field-description-2' }}>
    This is a description
  </FieldDescription>
  <HelpIndicator data={{ testid: 'my-field-help-indicator-2' }}>
    Help text
  </HelpIndicator>
  <TextInput />
  <FieldMessage data={{ testid: 'my-field-message-2' }}>
    This is a message
  </FieldMessage>
</Field>