> To build a Wix site agentically, or add Wix features like bookings or a store to a site you already have, follow https://www.wix.com/headless/skill.md
> 
> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - If a reference page seems to be missing its schema (parameters, return types, or type definitions), append `?schema=true` to its `.md` URL (e.g. `https://dev.wix.com/docs/contexts/contexts/stores/category-info/use-category-info-context.md?schema=true`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: TimeInput Component

## Article: TimeInput Component

## Article Link: https://dev.wix.com/docs/wix-design-system/components/form/time-input-component.md

## Article Content:

# TimeInput

_Components/Form_

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

## Overview

```jsx
() => {
  const [error, setError] = React.useState(null);

  const onChange = (value) => {
    setError(undefined);
  };

  const onInvalid = (errorInfo) => {
    if (errorInfo) {
      setError('Invalid value');
    }
  };

  return (
    <Box align="center" height="95px">
      <Box width="256px" display="block">
        <FormField
          label="Start time"
          status={error ? 'error' : undefined}
          statusMessage={error ? error : undefined}
        >
          <TimeInput
            value={new Date('2021/02/02 10:30')}
            onChange={onChange}
            onInvalid={onInvalid}
          />
        </FormField>
      </Box>
    </Box>
  );
};
```

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

```jsx
<StorybookComponents.Stack flexDirection="column">
  <TimeInput size="large" placeholder="Large" />
  <TimeInput size="medium" placeholder="Medium" />
  <TimeInput size="small" placeholder="Small" />
</StorybookComponents.Stack>;
```

#### 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%`.

```jsx
<StorybookComponents.Stack flexDirection="column">
  <StorybookComponents.Stack>
    <TimeInput width="auto" placeholder="Auto" />
  </StorybookComponents.Stack>
  <TimeInput width="100%" placeholder="Full width" />
</StorybookComponents.Stack>;
```

#### 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`.

```jsx
<StorybookComponents.Stack flexDirection="column">
  <TimeInput border="standard" placeholder="Standard" />
  <TimeInput border="round" placeholder="Round" />
  <TimeInput border="bottomLine" placeholder="Bottom Line" />
  <TimeInput border="none" placeholder="None" />
</StorybookComponents.Stack>;
```

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

```jsx
<StorybookComponents.Stack flexDirection="column">
  <TimeInput status="error" placeholder="Error" />
  <TimeInput status="warning" placeholder="Warning" />
  <TimeInput status="loading" placeholder="Loading" />
</StorybookComponents.Stack>;
```

#### 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/>`.

```jsx
<StorybookComponents.Stack flexDirection="column">
  <StorybookComponents.Stack flexDirection="column" gap="12px">
    <Text secondary>For all default cases:</Text>{' '}
    <FormField status="error" statusMessage="This is an error message.">
      <TimeInput placeholder="See message below" />
    </FormField>
  </StorybookComponents.Stack>
  <StorybookComponents.Stack flexDirection="column" gap="12px">
    <Text secondary>For narrow layouts only:</Text>
    <TimeInput
      placeholder="Hover on status icon"
      status="error"
      statusMessage="This is an error message."
    />
  </StorybookComponents.Stack>
</StorybookComponents.Stack>;
```

#### 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:99 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`.

```jsx
<TimeInput invalidMessage="Enter a time in 12 hour format using AM or PM." />;
```

#### Disabled

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

```jsx
<TimeInput disabled />;
```

#### Prefix & suffix

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

```jsx
<StorybookComponents.Stack flexDirection="column">
  <TimeInput
    prefix={<Input.Affix>From</Input.Affix>}
    suffix={<Input.Affix>GMT+1</Input.Affix>}
  />
</StorybookComponents.Stack>;
```

#### Locale

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

```jsx
<StorybookComponents.Stack flexDirection="column">
  <TimeInput locale="en" />
  <TimeInput locale="de" />
</StorybookComponents.Stack>;
```

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

```jsx
<StorybookComponents.Stack flexDirection="column">
  <TimeInput timeStyle="short" />
  <TimeInput timeStyle="long" />
</StorybookComponents.Stack>;
```

#### Step

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

By default, the interval between timestamps is 15 minutes.

```jsx
<StorybookComponents.Stack>
  <StorybookComponents.Stack flexDirection="column" gap="6px">
    15 min (default):
    <TimeInput step={15} />
  </StorybookComponents.Stack>
  <StorybookComponents.Stack flexDirection="column" gap="6px">
    5 min:
    <TimeInput step={5} />
  </StorybookComponents.Stack>
  <StorybookComponents.Stack flexDirection="column" gap="6px">
    30 min:
    <TimeInput step={30} />
  </StorybookComponents.Stack>
  <StorybookComponents.Stack flexDirection="column" gap="6px">
    60 min:
    <TimeInput step={60} />
  </StorybookComponents.Stack>
</StorybookComponents.Stack>;
```

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

```jsx
() => {
  const [error, setError] = React.useState(null);

  const onChange = (value) => {
    setError(undefined);
  };

  const onInvalid = (errorInfo) => {
    if (errorInfo.validationType === 'outOfBoundsError') {
      setError('Past time values are not allowed');
    } else if (errorInfo.validationType === 'formatError') {
      setError('Invalid format');
    }
  };

  return (
    <StorybookComponents.Stack flexDirection="column">
      <FormField
        status={error ? 'error' : undefined}
        statusMessage={
          error
            ? error
            : 'Try entering invalid (e.g. 12:99 PM) or past time values to see different error messages'
        }
      >
        <TimeInput excludePastTimes onChange={onChange} onInvalid={onInvalid} />
      </FormField>
    </StorybookComponents.Stack>
  );
};
```

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

```jsx
() => {
  const [error, setError] = React.useState(null);

  const onChange = (value) => {
    if (value.date?.getMinutes() !== 0) {
      setError('Value must match 1 hour interval');
    } else {
      setError(undefined);
    }
  };

  const onInvalid = (errorInfo) => {
    if (errorInfo) {
      setError('Invalid value');
    }
  };

  return (
    <StorybookComponents.Stack flexDirection="column">
      <FormField
        status={error ? 'error' : undefined}
        statusMessage={
          error ?? 'Try entering a value with minutes (e.g. 12:15 PM)'
        }
      >
        <TimeInput step={60} onChange={onChange} onInvalid={onInvalid} />
      </FormField>
    </StorybookComponents.Stack>
  );
};
```

#### Masked TimeInput using use-mask-input

_Requires use of external package. In this example `use-mask-input` package is used._

```jsx
() => {
  const { withMask } = require('use-mask-input');
  const maskRef = React.useMemo(
    () =>
      withMask('99:99', {
        placeholder: '_',
        showMaskOnHover: false,
      }),
    [],
  );
  return (
    <TimeInput
      locale="en-GB"
      inputRef={maskRef}
      disableAutoComplete
      autoSelect={false}
      invalidMessage="Enter a valid time"
    />
  );
};
```

### Common use case examples

#### Scheduling

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

```jsx
() => {
  const [startDate, setStartDate] = React.useState(null);
  const [endDate, setEndDate] = React.useState(null);

  return (
    <Layout>
      <Cell span={6}>
        <Box gap={2}>
          <FormField label="Start date">
            <DatePicker
              width="100%"
              placeholderText="Select"
              value={startDate}
              onChange={(value) => setStartDate(value)}
            />
          </FormField>
          <FormField label="Start time">
            <TimeInput />
          </FormField>
        </Box>
      </Cell>
      <Cell span={6}>
        <Box gap={2}>
          <FormField label="Start date">
            <DatePicker
              width="100%"
              placeholderText="Select"
              value={startDate}
              onChange={(value) => setStartDate(value)}
            />
          </FormField>
          <FormField label="Start time">
            <TimeInput />
          </FormField>
        </Box>
      </Cell>
    </Layout>
  );
};
```

#### Range

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

```jsx
<FormField label="Duration">
  <Range>
    <TimeInput />
    <TimeInput />
  </Range>
</FormField>;
```

## Code

```jsx
import { TimeInput } from '@wix/design-system';
```

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `autoSelect` | `boolean` | — | Specifies whether input is auto selected on focus. |
| `backgroundColor` | `string` | — | Sets the background color of the input. Accepts any CSS color value. |
| `border` | `"none" \| "standard" \| "round" \| "bottomLine"` | — | Control the border style of input. |
| `customInput` | `null \| 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>`. |
| `dataHook` | `string` | — | Applies a data-hook HTML attribute that can be used in the tests. |
| `disableAutoComplete` | `boolean` | — | 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. |
| `disabled` | `boolean` | — | Specifies whether component is disabled. |
| `disableKeyboardType` | `boolean` | — | 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. |
| `excludePastTimes` | `boolean` | — | 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 |
| `hideStatusSuffix` | `boolean` | — | Specifies whether status suffix is hidden. |
| `inputmode` | `string` | — | 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`. |
| `inputRef` | `null \| (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. |
| `invalidMessage` | `string` | — | 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. |
| `onBlur` | `FocusEventHandler` | — | Defines a standard input `onBlur` callback. |
| `onChange` | `({ date }: { date: Date \| null; }) => void` | — | Defines a callback function which is called on every time value changes. |
| `onFocus` | `FocusEventHandler` | — | 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 |
| `placeholder` | `string` | — | Sets a placeholder message to display. |
| `popoverProps` | `PopoverCommonProps` | — | Allows to pass all common popover props. |
| `prefix` | `ReactNode` | — | Pass a component you want to show as the prefix of the input, e.g., text, icon. |
| `readOnly` | `boolean` | — | Specifies whether input is read only. |
| `ref` | `null \| 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. |
| `statusMessage` | `ReactNode` | — | Defines the message to display on status icon hover. If not given or empty, no tooltip is displayed. |
| `step` | `number` | `15` | Specifies the interval between time values shown in dropdown. |
| `suffix` | `ReactNode` | — | 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()` |
| `value` | `null \| Date` | — | Specifies the current value of the input. |
| `width` | `string \| 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](invalid-url))
- **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](invalid-url))
- **1.189.1** (2025-05-16) — fix: add clear to TimeInput actions type ([#14865](invalid-url))
- **1.188.0** (2025-05-12) — feat: exposed imperative handle to clear the value ([#14833](invalid-url))
- **1.187.0** (2025-05-07) — fix: loophole with onInvalid function call ([#14821](invalid-url))
- **1.183.0** (2025-04-24) — fix: add missing hideStatusSuffix to index.d.ts ([#14793](invalid-url))
- **1.182.0** (2025-04-23) — feat: add hideStatusSuffix prop to TimeInput ([#14768](invalid-url))
- **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](invalid-url))
- **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](invalid-url))
- **1.92.1** (2024-02-05) — maintenance release, no component-specific changes