Skip to content
On this page

Field

A form field with a label, an input or control, and an optional validation message.

Guidelines

Using fields

Field provides features for building an accessible, understandable form field to collect user input.

Example of a Codex Field with different field items: with a text input, with a select, and with a checkbox group.

Use the Field component to create form layouts and to create a variety of form inputs, such as text inputs, selects, radio buttons, checkboxes or toggle switches.

If you do not need to collect user input, do not use Field. For example, Field is not necessary to display a search input. Although search is built with a text input component, it triggers an action and is not a form item.

Specifications

Specification of Field.

It is composed of the following elements:

  1. Label
    A label serves as a precise and informative title for the form field, indicating the type of information to be entered. It can also incorporate a description. Explore Label to check the different label properties.
  2. Field
    The input element, or a group of inputs, where the user enters information. Field can use any form item such as text input, select, checkbox, etc.
  3. Helper text (optional)
    Text that provides additional information related to the field.
  4. Validation message
    An inline validation message will appear to provide feedback about the status of the field. For example, to provide an error message to the user when the field contains one or more errors.

Refer to the Field component in Codex Figma.

Types

The Field component's control can be any form item component designed to gather user input, including:

  • Text input and text area
  • Select
  • Combobox
  • Checkbox, radio groups, and toggle switch
  • Chip input
  • Lookup

However, components not intended for collecting user input, such as SearchInput, should not be used within Field.

Types of Fields based on its field content: with a text
input, with a select, with a combobox, with a checkbox group, with a radio group, and with a
toggle switch group.

A complex field may comprise multiple inputs, each accompanied by an individual label that can be visually concealed.

A Field component with two field items and an action affecting it all.

The helper text slot can include plain text with or without links.

A Field component with a helper text including a link.

When combining the Field component with TextArea, you can use a custom character counter within the helper text section. For non-TextArea items like TextInput, character counters are not used, as they are not relevant for shorter inputs.

The character counter counts down as the user types, turning into an error state when the character limit is exceeded. It displays the number of exceeded characters as negative numbers along with an inline error message, informing the user that the entered message or text is too long.

Example of a Field with a text area and characters counter.

Interaction states

Form fields have the following visually separate states:

Interaction states of the Field component: default, hover on field, focus field, filled field, disabled, read-only field, error, warning and success.

  1. Default
  2. Hover on field item
  3. Focused field item
  4. Filled field item
  5. Disabled
  6. Read-only
  7. Error
  8. Warning
  9. Success

The interactive states will exclusively impact the field item within Field. Hover, focus, filled, and read-only states apply solely to the field item (e.g. the text input).

Demos

Configurable

Note that this configurable demo is only shown with a TextInput inside the Field. See the demos below for use of the Field component with other types of inputs or groups of inputs, along with code samples.

See the validation and error state demo below for more information about how to add and customize an error message.

Short description text
Longer help text to explain how to use this field
NameValue
Props
labelIcon
optionalFlag
hideLabel
isFieldset
disabled
status
Slots
label
description
help-text
View
Reading direction
Note: For icon properties, the relevant icon also needs to be imported from the @wikimedia/codex-icons package. See the usage documentation for more information.

With rich description and help text

You can include markup in the description and help-text slots. Only links and text formatting are recommended as description and help text should be concise.

With validation and error state

You can display a validation message based on the current status of the field. Set the status prop based on the field's validity, then pass in an object of messages keyed on validation status type. If there is a message for the current status, it will be displayed.

The status you bind to the Field component will also be passed down to its child components, which will display appropriate styles for that status (e.g. a red border in the error state). You do not need to bind the status prop to the child input components.

Setting the status based on field validity is up to you. In the example below, it's done as you're changing the input. You could also validate on blur to give the user a chance to finish filling out the field.

Try entering a username into the field below that's longer than a single character to see the error state and error message.

Enter a unique username
Username cannot be longer than 1 character

Fieldsets

For any field that contains multiple inputs or controls, set the isFieldset prop to true. This will output a <fieldset> element with a <legend> instead of a label. Below are some examples of fieldsets.

Radio group

Groups of Radio or Checkbox components are considered fieldsets.

Notifications Choose how often you'd like to receive notifications
Note that you can update this preference later

Complex field with two inputs

The field below has two inputs, a TextInput and a Select. In addition to the field-level label, each input needs its own individual label. In this case, the individual labels can be visually hidden. In the example below, the labels are included in two different ways:

  • For the TextInput, the Label component is used with hideLabel set to true
  • For the Select, an aria-label is applied

Note that, when you enter erroneous data in the TextInput below, error styles for both the TextInput and the Select will display since they are both contained in a single Field. If you need to show separate states for each input, see the nested Fields example below.

Coordinate location
Please enter coordinates as decimal degrees.

Fieldset with nested Fields

In this example, each input within the field needs its own visible label, description, validation status, and validation message. To accomplish this, each input is wrapped in a Field component. The entire field is wrapped in a top-level Field component with isFieldset set to true.

Note that each sub-field has its own status. This enables you to show error styles only for the input that contains the error, not the entire fieldset.

Nested fields will become disabled when their parent field is disabled.

Item weight
Numerical value of the weight
Must be from pre-approved list of units
Hint: try searching for "grams"

With custom help text content

The help-text slot is not limited to static text – more complex markup, including other components and bound values, can be provided here as well. Below is an example of a custom character counter embedded inside a Field. The counter is bound to the modelValue of the TextArea component inside the Field, and an error message is displayed if this text exceeds the maximum allowed number of characters.

Please enter a message of 100 characters or less

100

Vue usage

This component can wrap the following:

  • A single form input or control
  • An input group (e.g. a group of Radios or Checkboxes)
  • A set of nested fields (inputs wrapped in their own Field components).

The following Codex components can be used inside the Field component:

  • Checkbox
  • ChipInput
  • Combobox
  • Lookup
  • Radio
  • SearchInput
  • Select
  • TextArea
  • TextInput
  • ToggleSwitch

Props

Prop nameDescriptionTypeValuesDefault
labelIconIcon before the label text.

Do not use this if including a start icon within the input component.
Icon-''
optionalFlagText to indicate that the field is optional.

For example, this might be '(optional)' in English. This text will be placed next to the label text.
string-''
hideLabelWhether the label should be visually hidden.

Note that this will also hide the description.
boolean-false
isFieldsetWhether this field contains a group of inputs.

When true, this outputs a <fieldset> element with a semantic <legend>. When false, it outputs a <div> with a semantic <label>.
boolean-false
disabledWhether the entire field is disabled.boolean-false
statusstatus attribute of the input.ValidationStatusType'default', 'error''default'
messagesMessage text keyed on validation status type.ValidationMessages-() => { return {}; }

Slots

NameDescriptionBindings
labelLabel text.
descriptionShort description text.
defaultInput, control, or input group.
help-textFurther explanation of how to use this field.

CSS-only version

See the CSS-only Label docs for instructions on making the label visually-hidden or adding a label icon.

Markup structure

Single input

Short description text

Fieldset

Inside a <form>, use a <fieldset> element for input groups.

When outputting a <fieldset>, the markup of this component is quite different:

  • The outer element is the <fieldset> instead of a <div>
  • A <legend> is used instead of a <label>. See docs on the CSS-only Label for more info.
  • The description is included inside the <legend>
  • The for and aria-describedby attributes are not needed
Legend text (optional) Short description text

With help text

To add help text below the input or control:

  • Add the .cdx-field__control--has-help-text class to the control wrapper
  • Add a <div> below the control wrapper with the class .cdx-field__help-text

This works with single fields and fieldsets.

Disabled

To display a disabled field:

  • Add the .cdx-field--disabled class to the outer element
  • Add the .cdx-label--disabled class to the .cdx-label element
  • Disable the input(s) or control(s) (in the example below, the disabled attribute is added to the <input> element)

This works with single fields and fieldsets.

Error status and message

To display error styles and show an error message:

  • Add the .cdx-field--status-error class to the outer element
  • Apply error styles to the input (in the example below, the .cdx-text-input--status-error class is applied to the text input wrapper)
  • Add the validation message below the control wrapper