TimeInput

Components/Form

Interactive docs page: https://wix-pages.com/design-system-documentation/#/component/timeinput

Overview

Copy

Time inputs allow users to to enter or select a specific time value.

Do

  • Use time input to select a specific time. For example, to set an event start time, schedule an appointment, or set an alarm.

Don't

  • Don't use it to specify duration. Use <NumberInput/> instead.

Feature examples

Size

Adjust the size of the input using the size prop. 3 sizes are supported:

  • For most common cases, use the default medium.
  • Use large when the time input needs emphasis.
  • In more dense and compact layouts, use small.
Copy

Width

Control the width of the input with the width property. 2 values are supported:

  • To adjust the width of the field according to the size of the value use the default auto.
  • Fill the parent container completely with 100%.
Copy

Border

Style the component using the border prop. It supports 4 styles:

  • For most common cases, use standard.
  • To build inputs that can be used to filter data, use round.
  • Use bottomLine to create an editable, underlined title field.
  • When a component provides its own hover and focus styles, such as a table or spreadsheet cells, use none.
Copy

Status

Control the status of the time input using the status prop. It supports 3 states:

  • error demonstrates that something is missing or the entry was invalid. The conditions for an error status must be defined when using this prop.
  • warning highlights an input value that might have a significant impact to the user or it can't be validated.
  • loading shows when an input value is being uploaded to the server.
Copy

Status message

Add text that explains the status or what action the user should take with the statusMessage prop.

Showing the status message inline, directly below the input is preferred in all default cases.

  • To add an accessible inline message, wrap the component in a <FormField/> and add the statusMessage.
  • To add a status message in a tooltip that requires users to hover on the icon, use the statusMessage prop. Control tooltip placement with tooltipPlacement prop.

View more inline status message examples in <FormField/>.

Copy

Invalid message

To add predefined validations to the Time Input, use the invalidMessage prop.

The error icon and tooltip message are triggered when a user enters an invalid syntax, e.g., 15

am.

To exclude past times from the calendar view, use the excludePastTimes prop. To exclude specific times, use the filterTime prop.

The error message shows in a tooltip on hover over the icon by default. The message can be updated or removed.

Note: When both statusMessage and invalidMessage props are used, the input will display the statusMessage, unless internal validation fails. Then it would display the invalidMessage.

Copy

Disabled

Disable all input interactions with the disabled prop. Use it to demonstrate that the user cannot select the time.

Copy

Prefix & suffix

Add text, icons or a button at the beginning or end of an input field using prefix and suffix.

Copy

Locale

Specify a correct time formatting (e.g., AM/PM or military time) per country using the locale prop.

Copy

Time style

Control whether to display the time zone info with timeStyle. It supports 2 values:

  • short (the default) displays the time only.
  • long shows the time together with the time zone.
Copy

Step

In a dropdown layout, control the interval between timestamps using the step prop.

By default, the interval between timestamps is 15 minutes.

Copy

Developer examples

Predefined time validations

The component's validations cover the following cases:

  • formatError: when a user enters a time that's invalid and impossible to parse.
  • outOfBoundsError: when a user types in a time out of the accepted range. This validation is triggered when the excludePastTimes or filterTime props are enabled.

Note: In order for the error to be cleared, use onChange. This way, the error will not show when the user enters a valid time.

Copy

Custom time validations

To apply custom validations to the component, use information returned by onChange and onInvalid props. The onInvalid prop provides validationType and input value parameters.

Copy

Masked TimeInput using use-mask-input

Requires use of external package. In this example use-mask-input package is used.

Copy

Common use case examples

Scheduling

Use the time input together with a <DatePicker/> to schedule specific times for events, appointments, delivery hours, etc.

Copy

Range

Use the <Range/> component to merge two input fields to specify a time duration.

Copy

Code

Copy

Props

NameTypeDefaultDescription
autoSelectboolean—Specifies whether input is auto selected on focus.
backgroundColorstring—Sets the background color of the input. Accepts any CSS color value.
border"none" | "standard" | "round" | "bottomLine"—Control the border style of input.
customInputnull | string | number | false | true | Function | ReactElement<any, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal—Render a custom component in place of the default <input>. Must be a React.forwardRef component that forwards the ref to a real <input>.
dataHookstring—Applies a data-hook HTML attribute that can be used in the tests.
disableAutoCompleteboolean—Disables the auto-suggest UX (closest-time pre-fill, suggestion autofill, mid-typing format validation). The dropdown still works as a picker. Use when integrating an external input mask. Format errors surface on blur.
disabledboolean—Specifies whether component is disabled.
disableKeyboardTypeboolean—Specifies whether typing into the field is blocked, leaving the stepper controls as the only way to change the time.
enterKeyHint"search" | "enter" | "done" | "go" | "next" | "previous" | "send"—Sets the label of the virtual keyboard's enter key on touch devices.
excludePastTimesboolean—Specify whether past time slots should be shown or not.
filterTime(time: Date) => boolean—Specify selectable time slots: * param {Date} value - a time to check * return {boolean} - true if value should be shown in time slots dropdown, false otherwise
hideStatusSuffixboolean—Specifies whether status suffix is hidden.
inputmodestring—Sets the native inputmode attribute, which picks the virtual keyboard on touch devices. Supported values are none, text, decimal, numeric, tel, search, email and url.
inputRefnull | (instance: HTMLInputElement | null) => void | RefObject<HTMLInputElement>—Ref to the underlying <input> DOM element. Accepts callback and object refs. Use for input masking libraries. Memoize callback refs to avoid reattaching.
invalidMessagestring—Enables internal validation and defines a message to display when user types invalid time value.
locale"th" | "tr" | "id" | "fr" | "no" | "en" | "en-US" | "en-GB" | "en-AU" | "en-CA" | "ar" | "bg" | "ca" | "zh" | "zh-TW" | "zh-HK" | "zh-MO" | "cs" | "da" | "nl" | "fi" | "fr-CA" | "fr-CH" | "fr-BE" | "de" | "de-CH" | "de-AT" | "el" | "he" | "hi" | "hu" | "it" | "ja" | "ko" | "lt" | "ms" | "nb" | "nn" | "pl" | "pt-BR" | "pt" | "ro" | "ru" | "sk" | "sl" | "es" | "es-419" | "es-AR" | "es-MX" | "es-US" | "sv" | "tl" | "uk" | "vi"—Sets locale and formats time according to it.
onBlurFocusEventHandler—Defines a standard input onBlur callback.
onChange({ date }: { date: Date | null; }) => void—Defines a callback function which is called on every time value changes.
onFocusFocusEventHandler—Defines a standard input onFocus callback.
onInvalid(info: { validationType: "outOfBoundsError" | "formatError"; value: string; }) => void—Defines a callback function which is called on cases when invalid time is typed or confirmed with an action. - return {{ validationType: 'formatError' | 'outOfBoundsError', value: string }} - validationType - type 'formatError'is set when value is in the wrong time format - type 'outOfBoundsError' is set when excludePastTimes or filterTime is used and value doesn't match the filters - value - is set to current input value
placeholderstring—Sets a placeholder message to display.
popoverPropsPopoverCommonProps—Allows to pass all common popover props.
prefixReactNode—Pass a component you want to show as the prefix of the input, e.g., text, icon.
readOnlyboolean—Specifies whether input is read only.
refnull | string | (instance: TimeInputImperativeActions | null) => void | RefObject<TimeInputImperativeActions>—Allows getting a ref to the component instance. Once the component unmounts, React will set ref.current to null (or call the ref with null if you passed a callback ref).
size"small" | "tiny" | "medium" | "large"—Controls the size of the input.
status"error" | "warning" | "loading"—Specify the status of a field.
statusMessageReactNode—Defines the message to display on status icon hover. If not given or empty, no tooltip is displayed.
stepnumber15Specifies the interval between time values shown in dropdown.
suffixReactNode—Pass a component you want to show as the suffix of the input, e.g., text, icon.
timeStyle"short" | "long"—Specifies what time formatting style to use when calling format()
valuenull | Date—Specifies the current value of the input.
widthstring | number | string & {}—Controls the width of the component. auto resizes the input to match the width of its contents, while 100% takes up the full parent container width.

Testkit

No testkit for this component — it doesn't expose a unidriver testkit.

Changelog

  • 1.344.0 (2026-10-28) — maintenance release, no component-specific changes
  • 1.340.0 (2026-10-21) — maintenance release, no component-specific changes
  • 1.339.0 (2026-10-19) — maintenance release, no component-specific changes
  • 1.338.0 (2026-10-15) — maintenance release, no component-specific changes
  • 1.335.0 (2026-10-12) — feat: inside WixDesignSystemProvider with mobile, tapping the field opens the list of times and keeps it open until a time is picked or the drawer is dismissed, and onBlur fires once the drawer closes rather than on the tap. DropdownBase: new onClose(reason) callback, so a parent that controls open can close it on an outside press, Esc or a drawer drag, and a tap on the mobile drawer's overlay now reaches onClickOutside as on desktop. Drawer: onClose receives the reason ('outside-press', 'escape-key', 'drag' or 'focus-out') as a second argument. (#17289)
  • 1.331.0 (2026-10-01) — maintenance release, no component-specific changes
  • 1.330.3 (2026-09-29) — maintenance release, no component-specific changes
  • 1.330.0 (2026-09-28) — maintenance release, no component-specific changes
  • 1.328.0 (2026-09-22) — maintenance release, no component-specific changes
  • 1.325.0 (2026-09-17) — maintenance release, no component-specific changes
  • 1.320.0 (2026-09-03) — maintenance release, no component-specific changes
  • 1.312.0 (2026-08-14) — maintenance release, no component-specific changes
  • 1.310.0 (2026-08-10) — maintenance release, no component-specific changes
  • 1.292.0 (2026-06-22) — maintenance release, no component-specific changes
  • 1.279.0 (2026-05-13) — maintenance release, no component-specific changes
  • 1.266.0 (2026-04-07) — maintenance release, no component-specific changes
  • 1.260.0 (2026-03-17) — maintenance release, no component-specific changes
  • 1.239.0 (2025-12-12) — maintenance release, no component-specific changes
  • 1.229.0 (2025-11-18) — maintenance release, no component-specific changes
  • 1.225.0 (2025-11-07) — maintenance release, no component-specific changes
  • 1.224.0 (2025-10-30) — maintenance release, no component-specific changes
  • 1.220.0 (2025-09-29) — maintenance release, no component-specific changes
  • 1.202.0 (2025-06-27) — fix: add missing aria attributes (#14991)
  • 1.189.1 (2025-05-16) — fix: add clear to TimeInput actions type (#14865)
  • 1.188.0 (2025-05-12) — feat: exposed imperative handle to clear the value (#14833)
  • 1.187.0 (2025-05-07) — fix: loophole with onInvalid function call (#14821)
  • 1.183.0 (2025-04-24) — fix: add missing hideStatusSuffix to index.d.ts (#14793)
  • 1.182.0 (2025-04-23) — feat: add hideStatusSuffix prop to TimeInput (#14768)
  • 1.169.0 (2025-03-10) — maintenance release, no component-specific changes
  • 1.165.0 (2025-02-27) — maintenance release, no component-specific changes
  • 1.149.0 (2024-12-19) — feat: add new prop disableKeyboardType (#14393)
  • 1.138.1 (2024-10-30) — maintenance release, no component-specific changes
  • 1.115.0 (2024-07-17) — maintenance release, no component-specific changes
  • 1.102.0 (2024-04-16) — fix: removed mutating original date object of value prop (#13623)
  • 1.92.1 (2024-02-05) — maintenance release, no component-specific changes

Last updated: 30 October 2026

Did this help?