Form

The form component is a wrapper that doesn't render anything itself. Child elements must be added for it to function as a form.

The form component passes props and information down into the <form> element and its children. This includes information about whether the form is dirty, disabled, reset or submitting.

Each form needs a header and footer, and form sections can be added to the body of a form. 'Field' is used as a container for form fields and 'Fieldset' groups related fields and form controls.

People can submit a form when all fields are valid. Submitting the form calls the 'onSubmit' function.

If your form component only requires spreading formProps on the HTML <form> element and doesn't utilize any of the other render props like submitting, you can simplify how it's written in your code.

Props can be added to the underlying <form> element by applying valid props to the atlaskit Form component. If the prop is not directly supported by the atlaskit Form component, you can add any other props to formProps.

In the simplified form, all of the form component's children are already wrapped within an HTML <form> element, including all necessary props as well as those provided on the form component.

The layout of a form is made up of 3 main areas: header, section, and footer.

A form header includes the title and an optional description of the form content.

If your form contains required fields, the form header should include the legend 'Required fields are marked with an asterisk *' so sighted users know that an asterisk * indicates a required field.

Use a form section to group related information together and make longer forms easier to understand. Form section is a higher-level wrapper than Fieldset.

An optional description can be added to a section and multiple form sections can be used in one form.

Use a form footer to set buttons at the end of the form. The footer is positioned after the form's last field.

Read more about button positioning.

Field allows for an entry in the form. It comes with props that give more information about the field state, which can be passed on to the inner component.

CheckboxField, RangeField, and CharacterCounterField are part of the form package.

When a person focuses on a Field and starts changing content, the focus color becomes blue.

If your field only requires spreading fieldProps on the input element and doesn't use any other render props like meta, you can simplify how it's written in your code by putting the contents of your field within the component prop and omitting the messaging component (for example, ErrorMessage).

This simplified implementation will provide greater accessibility and more consistent styling through rendering components of your field internally.

If an error is returned by the function provided in the validate prop, it will be rendered automatically in an internal ErrorMessage component. Content that would previously go in the HelperMessage and ValidMessage components will be rendered when provided using the helperMessage and validMessage props.

If you need more control of how messaging or labeling renders, don't use this simple implementation of a Field.

Use a Fieldset element to group related fields under a heading. It's useful to group components like checkboxes and text inputs that are related, like the fields that make up an address.

Use legend to assign a caption to the Fieldset, as this improves accessibility for when the Fieldset is rendered non-visually for screen readers.

CheckboxField lets people select one or more options from a number of choices. It should have a label prop that renders the label inline with the checkbox.

By default, the value of a CheckboxField is true or false. Use the value prop to pass a value when the field is checked. This will return an array that contains value.

When grouping checkboxes using Fieldset, they should all have the same name prop value so they're grouped properly. For example, in a Fieldset that allows multiple selections, submitting the form will show the chosen options as the value of that field.

RangeField allows people to choose an approximate value on a slider.

It requires defaultValue to set the initial state, as well as a name prop so that it defines the RangeField for form submission.

Default values for the range component are from 0 to 100 with increments of 1. This can be adjusted by specifying the min, max, and step props.

A character counter field provides real-time feedback about text length as people type, showing how many characters are remaining or have been exceeded.

Use it when there are constraints on text length, such as database limits, technical requirements, or design constraints.

Configure minimum length with minCharacters and maximum length with maxCharacters. With these props, the counter automatically updates its message and styling based, showing either:

This field is more accessible than using native HTML maxLength and minLength attributes, as it provides clear visual feedback and screen reader announcements about character count changes, helping users stay within limits before form submission.

You can customize feedback messages using the underMinimumMessage,underMaximumMessage, and overMaximumMessage props.

For validation beyond character limits, combine the character counter logic with the validate prop to implement custom validation rules (such as checking for specific patterns, forbidden characters, or business logic requirements).

The CharacterCounter component can also be used for custom implementations. This is useful when you're building custom form layout experiences or need character counting in non-form contexts. Do note this should generally not be used and instead use CharacterCounterField for better consistency across forms.

When using standalone, you're responsible for:

Fields in a form are made up of components and rendered by using field. Any component with a value and onChange handler can be a field. The component renders inside a field and adds an entry to the form state.

A text field component is a space for people to write or edit text. Use for text that spans one line.

At a minimum, use a name prop to provide the form component with the name of the field. The props allowed on a text field also extend the native HTML input element.

When there's a need for long-form plain text that spans multiple lines, use a text area component.

A select component allows people to make single or multiple selections from a dropdown list of options.

To show options in the list, the select component needs the passing in of listed options in the options prop. An empty options prop will render the words 'No options' in the drop down.

Use a radio component if people need to choose only one option from a number of choices.

Provide the label prop to add an inline label. Provide the value prop to define the value that is submitted to the form.

To group radios, wrap them in a radio group component to semantically indicate the radios are together.

To ensure correct grouping, either use the name prop on the radio group component or make sure all radios within the group have the same name. Failure to do so will cause incorrect grouping.

A date time picker component lets someone easily select a date and/or time.

To define specific props for the underlying pickers (date and time), use datePicker props and timePicker props.

A toggle component allows someone to turn something on or off.

Include a visible label with the toggle. When there isn't a visible label you can pair a toggle with, use the label prop to tell people who use assistive technology what the toggle is for.

This example shows you how a form could look with every possible input included and with required fields.

Use validation messages to show when a form submission fails or requires more information. Keep messages short and for help writing them, use error messaging guidelines.

When validating text fields, styles will switch depending on whether it’s an error or warning message type. For example, helper text turns into an error message when someone's input doesn't fit the criteria. Error and warning messages disappear when the criteria is met.

To ensure error messages are rendered through assistive technologies, wrap them in MessageWrapper and make sure they're in the DOM at the time the form is rendered.

Validate a field's value using the validate prop. This accepts a function that receives the current field value and is called whenever a field value changes.

Return an error when it is invalid. Otherwise, return undefined.

On submission, the current state gets passed onto the onSubmit handler.

For submission errors, the onSubmit handler should return an object. For example, if there's a problem with the password field, the object should contain the key and the error as the value. If the submission succeeds, the onSubmit handler should return undefined.

The onSubmit handler can return synchronously or return a promise that resolves with the error. For successful asynchronous validation, the onSubmit handler would return a promise that resolves to undefined as there are no errors.

If validation requires an async check, the validation function can return a promise. The promise should resolve with the error rather than reject with the error.

Field-level and submission validation can also have async validation where they return promises.

Using the validating status in the meta prop helps with asynchronous validation and provides a better user experience. For example, a spinner reassures someone that validation is happening.

To display a form in a layer above the page, use it within a modal dialog component.

Keep the context of the form inside the modal, as people can't access anything outside of it while it's being filled in.

Buttons to submit the form should be aligned to the right, with the primary button to the right of a secondary button.

Use when you have a small amount of information to capture.

Buttons to submit the form should be aligned to the left, with the primary button to the left of a secondary button. This alignment aids scanning and helps people using screen magnifiers and who have a limited field of vision.

To use the current form state to generate a preview while someone is filling a form in, use the useFormState hook.

Don't use these values for any permanent storage or state. You should rely on form submission for the final values.

Include conditional fields in your form by checking the form state with useFormState.

This is particularly useful for building forms that have progressive disclosure.