Time Field

For development, import TimeField from @servicetitan/anvil2. For design, find it in the Anvil2 file.

Anatomy

The Time Field consists of nine primary elements that work together to allow users to enter a time into an input.

Label
Clock icon (permanent)
Hours (AM/PM variant)
Minutes (AM/PM variant)
AM/PM marker
Hours (24hr variant)
Minutes (24hr variant)
Options panel
Selected option

Options

The Time Field supports 12-hour and 24-hour format configurations to accommodate various time entry scenarios.

12hr vs. 24 hour

Time Field supports 12-hour and 24-hour formats. 12-hour format is the default.

Behavior

The Time Field responds to user interaction with distinct visual states, error handling, and min/max constraints.

Visual States

Erroring

Errors occur when the field is required and the developer has added definitions for isInputInvalid and isInputEmpty properties on blur.
When auto-rounding is set to true and the user enters a non-rounded value, the value updates on blur without erroring.
When users must enter a time at a particular interval, use an input with suggestions and steps instead of erroring to guide the user.
Read more about validation in the code tab.

Min/max setting

Input accepts both min and max values.
For option time fields, this sets the available options to a min and max based on the increment step.
Times outside the time frame constraints cannot be entered into the field.
Read more about min/max setting in the code tab.

Usage Guidelines

Standard	Requirement
DoInput a time	Use the Time Field when users need to input a time, such as recording when an event occurred or setting an appointment time.
DoLimited time frames	Only times within a range are valid, such as business hours set through min and max values.
DoFixed intervals	Users must enter times at set intervals, such as every 15 minutes, and options with steps guide the entry.
DoProvide an initial value	When possible, provide an initial value in the Time Field. For example, if appointments are only possible on a particular day between noon and 3pm, provide the time “12:00 PM” and allow the user to change it from there.
DoProvide min and max values	When possible, provide min and max values in the Time Field. For example, if appointments are only possible during business hours, add the opening and closing times as min and max values, so the user cannot make selections outside of the allotted time frame.
DoProvide intelligent time stops	Provide intelligent time stops for the user when selecting time if possible. For example, if the user can only input time(s) in 15 minute intervals, provide the options dropdown with that stop to help the user input their times correctly.
Don’tDates	Use a Date Field Single for a single date or a Date Field Range for a date span.
Don’tDurations	Use a Number Field with a suffix such as minutes for an amount of time rather than a time of day.

How to Use

When possible, provide an initial value in the Time Field. For example, if appointments are only possible on a particular day between noon and 3pm, provide the time “12:00 PM” and allow the user to change it from there. When possible, provide min and max values in the Time Field. For example, if appointments are only possible during business hours, add the opening and closing times as min and max values, so the user cannot make selections outside of the allotted time frame. Here, the Time Picker displays values between 9am and 5pm. Provide intelligent time stops for the user when selecting time if possible. For example, if the user can only input time(s) in 15 minute intervals, provide the options dropdown with that stop to help the user input their times correctly.

Content

Content within the Time Field should clearly communicate the expected time format through labels and placeholder text.

Keyboard Interaction

Users can navigate the Time Field using standard keyboard controls.

Key	Action
Up and down arrows	Moves up and down between options and the AM/PM in the dropdown
Enter	Selects the time and closes the dropdown selector

Code

Implementation
TimeField Props
TimeFieldChange Props

Common Examples

import { TimeField } from "@servicetitan/anvil2";

function ExampleComponent() {
  return (
    <TimeField
      label="Label Text"
      step={60}
      onChange={(change) => {
        // change function
      }}
    />
  );
}

With Suggestions Enabled (Default)

By default, time fields use a 12-hour format and present suggested times in a dropdown based on the step prop. The dropdown is only present if there is more than one valid option to select from. Whether the dropdown is present or not, the input allows typing in the field itself to get to your desired time.There is autocomplete for best guess assumptions of the time you might be going for based on a partial input value. If both AM and PM times both are possible options, AM takes precedence over PM for autocomplete.

Without Suggestions

When disableSuggestions is set to true, the suggestions dropdown will no longer appear. All other features, including autocomplete, will continue to work as the user types.

Auto-Rounding

If the autoround prop is set to true, the time field will attempt to round to the next valid time on blur based on the step and max props. Note: rounding will always go to the future, never the past.If suggestions are enabled, the suggestions will display the auto rounded options available, even if the time currently typed in the input is not yet rounded.Add a description to allow users to know auto rounding is enabled for the field.

Min and Max Constraints

Use the min and max props to set a time frame constraint. When the props are present, a time outside the time frame can not be entered into the field.Autocomplete will adjust to a time within the time frame if the partial value can fall within the constraint. For example, 02:— will autocomplete to 02:00 PM for a 09:00 AM - 05:00 PM time frame instead of the default 02:00 AM since 02:00 AM does not fall between 09:00 AM and 05:00 PM.autoround will cap at the max time even if it doesn’t fully align with the step prop. For example: In a field with a 09:00 AM - 05:00 PM time frame and a step of 30 minutes, if 4:45 is entered it will round to 5:00 PM.Add a description to allow users to know there is a time constraint.

24 Hour Format

Set the format prop to 24 to change to the time format. When using this format, ensure min and max times are also set to 24 hour format.

Validation

Validation needs to be handled with the onChange. isInputValid and isInputEmpty are boolean props returned with the time so that custom validation can be applied. Note: Because of the use of the mask acts as a value for the input, native html validation will not occur.

Markdown in labels

The label prop supports inline markdown: bold (**text**), italic (*text*), bold and italic (***text***), highlight (==text==), and code (`text`).

Hide the label

Use hideLabel to visually hide the label. The label string is converted to an aria-label on the input so it remains accessible to screen readers — any inline markdown is stripped to plain text.

<TimeField
  label="Label Text"
  autoround={false}
  defaultValue="09:00 AM"
  disableSuggestions={false}
  format="12"
  max="05:00 PM"
  min="09:00 AM"
  step={30}
  value="10:30 AM"
  onChange={(change) => console.log(change)}
/>

`TimeField` Props

In addition to the props listed below, the TimeField accepts most TextField props with the exception of type, placeholder, showCounter and maxLength. This includes label (supports inline markdown; omitting is deprecated) and hideLabel.

boolean

default:"false"

If true, value will round to nearest future step. If there is a defined time frame, the ceiling for rounding is the max time.

string | null

Uncontrolled initial value for the component.

boolean

default:"false"

If true, the dropdown with suggested time options is not present.

"12" | "24"

default:"12"

Time format for the component.

Omit<FieldLabelProps, "children" | "id" | "htmlFor">

Additional props passed to the FieldLabel component. Supports the aiMark prop for displaying AI-powered field indicators.

string

Maximum allowed time for a time frame. Must be paired with min. String must match the format set for the component.

string

Minimum allowed time for a time frame. Must be paired with max. String must match format set for the component.

(change: TimeFieldChange) => void

Callback fired on blur or after a time is selected from the selection list.

number

default:"30"

Time increments for the time suggestions and auto rounding.

string | null

Controlled value for the component.

// TimeFieldChange is returned by the onChange callback
const handleChange = (change: TimeFieldChange) => {
  console.log(change.isInputEmpty, change.isInputValid, change.time);
};

`TimeFieldChange` Props

The onChange callback receives a TimeFieldChange object with the following properties:

boolean

Whether the input is empty.

boolean

Whether there is a validation issue aside from empty value with the input.

string | null

The returned time string.

Concepts & Guidelines

Anvil2

Resources

Time Field - Web

Anatomy

Options

12hr vs. 24 hour

Behavior

Visual States

Erroring

Min/max setting

Usage Guidelines

How to Use

Content

Keyboard Interaction

Code

Common Examples

With Suggestions Enabled (Default)

Without Suggestions

Auto-Rounding

Min and Max Constraints

24 Hour Format

Validation

Markdown in labels

Hide the label

`TimeField` Props

`TimeFieldChange` Props

​Anatomy

​Options

​12hr vs. 24 hour

​Behavior

​Visual States

​Erroring

​Min/max setting

​Usage Guidelines

​How to Use

​Content

​Keyboard Interaction

​Code

​Common Examples

​With Suggestions Enabled (Default)

​Without Suggestions

​Auto-Rounding

​Min and Max Constraints

​24 Hour Format

​Validation

​Markdown in labels

​Hide the label

​TimeField Props

​TimeFieldChange Props

Anatomy

Options

12hr vs. 24 hour

Behavior

Visual States

Erroring

Min/max setting

Usage Guidelines

How to Use

Content

Keyboard Interaction

Code

Common Examples

With Suggestions Enabled (Default)

Without Suggestions

Auto-Rounding

Min and Max Constraints

24 Hour Format

Validation

Markdown in labels

Hide the label

`TimeField` Props

`TimeFieldChange` Props