TimeInput is a field where users enter a time. They can either type the time directly or use keyboard navigation to toggle between digits. 

• The user clicks or focuses on the TimeInput, which makes it active.
• A cursor appears in the input element, and either the 'hours' digits or 'minutes' digits are highlighted depending upon the cursors position.
• To enter a time, the user can:
  • Type the time.
  • Click the 'hours' or 'minutes' digits and using their keyboard arrows toggle digits up or down.
• When finished, the user navigates away from the TimeInput.

• To ask users to enter a specific time, such as when a medication was administered.

• To ask users to enter a date
• To ask users to enter a time and a date together
• To ask users to enter hours or minutes alone, but not a specific HH:MM time
• To ask users to enter a time range

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

Opening the Input (click vs. tab)

When users click the TimeInput field, the cursor highlights the hour digits or minutes digits depending upon click location.

When users navigate to the field using the Tab key, however, the hours field is highlighted by default. This helps data entry staff and other heavy keyboard users enter data quickly, without interruption.

Keyboard shortcuts

TimeInput supports these athenaOne date shortcuts:

• n = the current time

Options

• TimeInput supports AM/PM or 24 hour time cycles
• TimeInput supports time validation with minimum and maximum valid times
• TimeInput supports placeholder and default times
• TimeInput has timezone support

Required fields

Forge offers three display 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 (“Time of birth”, not “Date Of Birth”).

TimeInput’s default placeholder text uses the standard Time format for athenahealth apps: HH:MM. TimeInput can support both AM/PM and 24 hour time.

TimeInput uses the TimeField component from react-aria-components. This library was chosen because it is robust, composable, and covers many different components of interest to Forge. Over time, our hope is that existing Forge components can be refactored to be based on react-aria-components. This should make Forge more consistent with itself and better adhere to web accessibility standards.

In the spirit of the high composability of react-aria-components, TimeInput re-exports react-aria components that it uses or customizes. This includes: AriaDateInput, AriaFieldError, AriaLabel, AriaText, and AriaTimeField. Our hope is that re-exporting these piecemeal components will allow for easier customization of TimeField by applications.

One notable difference from other Form components, is that TimeInput can render a label, description and errors. This allows TimeInput to not require a FormField to get the same functionality. TimeInput is still compatible with FormField.

Implementation links

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

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