Time picker (Preview)

To add the TimePicker component to your app:

1
2
import { TimePicker } from '@forge/react';

Description

A time picker allows the user to select a specific time.

Props

Examples

Default

By default, the time field is used to select a time from the select menu.

1
2
import { Label, TimePicker } from "@forge/react";

const TimePickerDefaultExample = () => {
  return (
    <Label labelFor="default-time-picker-example">Choose time</Label>
    <TimePicker
    selectProps={{
        inputId: "default-time-picker-example",
    }}
    />
  );
};

Form

When using the time picker with the form component, include a label and helper text. For more information, see the form component.

1
2
import {
  Button,
  useForm,
  Form,
  FormFooter,
  Label,
  RequiredAsterisk,
} from "@forge/react";

const TimePickerFormExample = () => {
  const { handleSubmit, register, getFieldId } = useForm();
  return (
    <>
      <Form onSubmit={handleSubmit(console.log)}>
        <Label labelFor={getFieldId("time-picker")}>
          Scheduled run time <RequiredAsterisk />
        </Label>
        <TimePicker
          {...register("time-picker")}
          selectProps={{
            inputId: getFieldId("time-picker"),
          }}
        />
        <FormFooter>
          <Button appearance="primary" type="submit">
            Submit
          </Button>
        </FormFooter>
      </Form>
    </>
  );
};

Field label and message

Always use a label component for each field and associate the label to the field properly. Use the HelperMessage component for any optional field-related message.

Required field label

For required fields, always add RequiredAsterisk component next to the label.

Validation

This is how time picker behaves within forms.

Validation displays an error message related to the restrictions of the time picker.

When a user selects the time picker area, the focus color changes to blue. When validating time pickers in real-time, message icons switch based on the message type.

For example, helper text becomes an error message when the input content doesn't meet the criteria. Error and warning messages disappear when the criteria is met.

Keep helper text as short as possible. For complex information, provide a link to more information in a new browser tab. Use the messaging guidelines for more help.

1
2
import { 
    TimePicker
    Label,
    useForm,
    Form,
    FormFooter,
    Button,
    ErrorMessage,
    HelperMessage,
    ValidMessage,
    RequiredAsterisk
} from "forge/react";

const TimePickerFormValidationExample = () => {
  const { handleSubmit, register, getFieldId, formState } = useForm();
  const { errors, touchedFields } = formState;

  return (
    <Form onSubmit={handleSubmit(console.log)}>
        <Label labelFor={getFieldId("time-picker")}>
            Scheduled run time <RequiredAsterisk />
        </Label>
        <TimePicker
            {...register("time-picker", { required: true })}
            selectProps={{
                inputId: getFieldId("time-picker"),
            }}
        />
        {errors["time-picker"] && (
            <ErrorMessage>This field is required</ErrorMessage>
        )}
        {!touchedFields["time-picker"] && !errors["time-picker"] && (
            <HelperMessage>Help or instruction text goes here</HelperMessage>
        )}
        {touchedFields["time-picker"] && !errors["time-picker"] && (
            <ValidMessage>You have entered a valid datetime</ValidMessage>
        )}
        <FormFooter>
            <Button appearance="primary" type="submit">
                Submit
            </Button>
        </FormFooter>
    </Form>
  );
};

Internationalization

Locale

Use locale to display times in a format which is appropriate to users.

1
2
import { TimePicker, Label } from "@forge/react";

export const TimePickerLocaleExample = () => {
  return (
    <>
      <Label labelFor="timepicker-locale-en">English locale</Label>
      <TimePicker
          locale="en-US"
          selectProps={{
              inputId: "timepicker-locale-en",
          }}
      />
      <Label labelFor="timepicker-locale-ko">Korean locale</Label>
      <TimePicker
          locale="ko-KR"
          selectProps={{
              inputId: "timepicker-locale-ko",
          }}
      />
    </>
  )
}

Time formats

TimePicker supports customizing the format of times. Formats are given as strings and use the syntax specified at Modern JavaScript Date Utility Library.

• `timeFormat` determined how times are formatted.

Where possible use locale for time formatting, instead of a custom format.

Time formats should be informed by the user’s locale and the use case.

1
2
import { TimePicker, Label } from "@forge/react";

const TimePickerCustomTimeFormat = () => {
  return (
    <Label labelFor="timepicker-custom-format">Custom Time Format</Label>
    <TimePicker
      timeFormat="HH:mm"
      placeholder="13:30"
      selectProps={{
        inputId: "timepicker-custom-format",
      }}
    />
  )
}

Time editable

This allows the time field to be edited via keyboard prompts.

1
2
import { TimePicker, Label } from "@forge/react";

const TimePickerEditableExample = () => (
  <>
    <Label labelFor="timepicker-editable-time">Editable time example</Label>
    <TimePicker
      timeIsEditable
      selectProps={{
        inputId: "timepicker-editable-time",
      }}
    />
  </>
);