Input is a field where users add and edit short pieces of information in forms, workflows, and searches. You can set at input type to match the expected data (e.g., telephone numbers, passwords). 

• The user clicks or focuses on Input, which makes it active. 
• While the field is active, the user can enter and edit data in it. 
• When finished, the user navigates away from the Input.

• To request freeform data (i.e., data that can’t be selected in a predefined list, like the user’s name)
• To provide an option for “Other” at the end of a predefined list, as with Checkbox or RadioGroup

Forms with too many Input fields frustrate users, sometimes causing them to drop off. Keep data entry as concise as possible. 

Don’t use Input: 

• For data that's easier for users to enter by selecting an item in a predefined list, like US states  
• For data that isn't required to complete the task, like salutations (Mr., Mrs., etc.) 
• For data that could be detected automatically, like browser type 

Input can be used as a standalone component, but it’s better when used with Form and FormField. Form provides a consistent, responsive layout, and FormField adds features like labels, error message handling, and hint text.

Input types

Input can be optimized for these data types:

• Text
• Email
• Number
• Password
• Search
• Telephone
• Time
• URL

Some data types have a visual or functional impact in browsers. For example, a password Input’s contents are obscured to increase security. See the demos for examples (but know that this behavior differs across browsers and devices).

Use with an icon 

Input can show an icon inside the field, aligned left. This can provide context about the Input’s data type.

Tips for use in forms 

With FormField, the label appears to the left of Input by default. It indicates what information users should enter (“First name”).  

Always include a label with Input. Never use placeholder text instead of a label, because placeholder text disappears when the user interacts with the field. This is often a problem for users who are multitasking, tabbing quickly through a form, or have cognitive issues.

Use placeholder text only when guidance (such as an example of the expected data or very short instructions) will help users enter information. Placeholder text shouldn’t duplicate the label text.  

If your placeholder text is information required to complete the task, make it hint text instead. Hint text appears below the Input field, so it remains visible. Hint text is an option when using Input in FormField. If using Input by itself, hint text must be coded separately. 

Required fields

Forge offers three options to indicate required form fields. See Form for details.

Spacing and size

The height of this component and the vertical space around it vary according to the form layout (i.e., medium, compact, super-compact). See Form for details.

No additional information for this component. 

Use sentence case for label text (“Patient name”, not “Patient Name”).

Use sentence case for any placeholder text. If providing an example, use “e.g.,” as an introduction. Here are some examples of good placeholder text:

• Phone number: “e.g., 617-555-0101"
• Email address: “e.g., person@email.com”

Required fields

Use the required prop to mark the Input as required.

Forge offers 3 options to indicate required form fields. When using Form with this component, set Form’s requiredVariation prop. See Form for details.

Implementation links

Input 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.

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 accessability 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 { Input } 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 Input from '@athena/forge/Input';

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 Input from '@athena/forge/dist/Input';