Input
A field where users enter and edit data.
The Basics
What it is
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).
How it works
- 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.
When to use
- 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
When not to use
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
What to use instead
Use Textarea for longer text input.
Use Typeahead to enable suggestions while typing.
Use ReadOnlyInput to display form text that can’t be edited.
How to use
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
- Number
- Password
- Option to toggle between showing and hiding password, in Figma libraries this variant is a separate component called 'Input ShowHide'. In code, this is an additional property added to the base input component.
- 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).
Specify the correct input type for your use case.
Use the Text type for all inputs.
Use with an icon
Input can show an icon inside the field, aligned left. This can provide context about the Input’s data type.
Use an icon that matches the input type.
Pick an arbitrary or confusing icon.
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 a label to indicate what data users should enter.
Use placeholder text instead of a label.
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.
Include important information or helpful tips as hint text.
Use placeholder text for important instructions.
Style
Design details
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.
Placement and hierarchy
No additional information for this component.
Content
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”
Demos
Coding
Developer tips
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.
####Password Styling Any instance of an Input component whose type prop is assigned the value of password will automatically be rendered in Show/Hide mode. This auto opt in can be overridden by explicitly setting the showHide prop to false.
Repository
Implementation links
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 accessibility in mind. These components do break the recommendations listed above.
Import statements
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';