FormError is an alert that displays a message to draw attention to a particular error on an input. This should always be used with an input like component (ex. multi field) and should not be used as a standalone error.

• FormError appears under the input that generated it  

• FormError should have a description of how to resolve the error  

• To add an error to an input like component that does not have an existing error prop 

• To request additional information from the user to resolve a validation conflict  

• For components that already support errors with built in props (ex. Input)  

• For general alerts or banners 

FormError should only be used in conjunction with an input component and should follow the same locations as it is used in [FormField]. FormError takes an error message (see Content below for guidance) and an alert type. For deciding alert type please refer to [AlertTypes].  

FormError should always be placed immediately below or to the right of the generating input.

Error message 

FormField’s error message should be short, clear, specific, and easy to understand. The message should describe the problem. For example: 

• “Patient name is required” 

• “Email address should be in this format: name@domain.com” 

• “This file is too big to upload (maximum size is 25 MB)” 

For help writing error messages, see Content Guide. 

[“Developer tips” body text]

Implementation links

FormError directory in Bitbucket

Implementation details

It is strongly recommended to familiarize yourself with the Forge source code. While this documentation is a best effort to document the intent and usage of a component, sometimes some features only become clear when looking at the source code. Also, looking at Forge's source code may help identify and fix bugs in either your application or Forge itself.

Storybook files

Forge maintains at least one storybook file per component. While the primary audience for these files is typically the Forge team, these storybook files may cover usages of the component not covered by a demo. The storybook for the latest version of forge can be found at go/forge-storybook-lts.

Testing library

Forge strongly encourages using testing-library to write tests for your application.

"The more your tests resemble the way your software is used, the more confidence they can give you."

If you're having trouble testing a Forge component using testing-library, it would be a good idea to see how Forge tests its own components. For the most part, Forge tries to use screen.getByRole as much as it can, as that API provides the best feedback on a11y compliance. Forge discourages the use of document.querySelector and screen.getByTestId as both APIs encourage using implementation details to test your component, and discourage adding roles to your component.

With that being said, many of Forge's components were not built with accessibility in mind. These components do break the recommendations listed above.

In Nimbus applications

athenaOne serves the Forge bundle independently from your application's bundle. Importing Forge components directly from '@athena/forge' takes advantage of this feature.

import { FormError } from '@athena/forge'

In standalone applications

Importing components using the exact path to the module takes advantage of webpack's tree shaking feature. Webpack will include only that module and its dependencies.

import FormError from '@athena/forge/FormError';

To use this import guidance, Typescript applications must use typescript >= 4.7.3, and should add this setting to their tsconfig.json file:

{
  "compilerOptions": {
    "moduleResolution": "Node16",
  }
}

If this setting doesn't work for your application, use this import statement instead:

import FormError from '@athena/forge/dist/FormError';