MUI Components
NPM

Time Pickers

These components wrap the Material UI X Time Picker with the suite's label, error and helper-text handling.

Use a time picker when you need a time of day without a date, such as an appointment slot, a shop's opening hours or an alarm. The value is a date object from your date library in which only the hours and minutes matter, so the date part is just a placeholder that you can leave alone or replace when you submit.

Each time picker comes in four variants:

  • MUITimePicker — responsive (renders the desktop UI on pointer devices, the mobile UI on touch).
  • MUIDesktopTimePicker — always renders the desktop (keyboard-first) UI.
  • MUIMobileTimePicker — always renders the mobile (modal) UI.
  • MUIStaticTimePicker — an always-visible inline picker with no text field.

All of these share the same controlled contract — a value in your date library's format and an onValueChange callback.

Setup

All pickers read their date adapter from ConfigProvider. Wrap your app once and pass the adapter for your date library (Day.js, Luxon, date-fns or Moment).

import { ConfigProvider } from '@nish1896/mui-components/config';
import { AdapterDayjs } from '@mui/x-date-pickers/AdapterDayjs';

<ConfigProvider dateAdapter={AdapterDayjs}>
  <App />
</ConfigProvider>
Warning

Without a dateAdapter, the pickers throw at render — this is the one required piece of setup.

Usage

import { MUITimePicker } from '@nish1896/mui-components/mui-pickers/time';
import { type Dayjs } from 'dayjs';
const [value, setValue] = useState<Dayjs | null>(null);

<MUITimePicker
  fieldName="time"
  value={value}
  onValueChange={({ newValue, context }) => setValue(newValue)}
/>

value uses the date type of your date adapter, such as a Dayjs for AdapterDayjs, where only the time of day matters, and null or undefined clears the picker. newValue has the same type, inferred from the value you pass. onValueChange receives { newValue, context } and is called for every change, including entries that aren't valid times, so check context.validationError before relying on newValue.

Other variants

The other three variants are exported from the same module and take the same props. Use MUIDesktopTimePicker for the keyboard-first popover on every device, MUIMobileTimePicker for a modal dialog, and MUIStaticTimePicker for an always-visible clock without a text field (see the note below the API table).

import {
  MUIDesktopTimePicker,
  MUIMobileTimePicker,
  MUIStaticTimePicker
} from '@nish1896/mui-components/mui-pickers/time';

<MUIMobileTimePicker
  fieldName="reminder"
  value={value}
  onValueChange={({ newValue }) => setValue(newValue)}
/>

onAccept is passed through to MUI X and fires when the user finishes picking a value.

12-hour or 24-hour clock

By default the clock follows the locale. Set ampm to false for a 24-hour clock, or true for a 12-hour clock with an AM/PM switch.

<MUITimePicker
  fieldName="departure"
  value={value}
  onValueChange={({ newValue }) => setValue(newValue)}
  ampm={false}
/>

Validation and time limits

Limit the selectable times with the MUI X props minTime, maxTime, minutesStep and shouldDisableTime, and with disablePast and disableFuture.

Disabled times can't be picked on the clock, and a typed time outside the limits is reported through context.validationError. It is one of 'invalidDate', 'minTime', 'maxTime', 'minutesStep', 'disablePast', 'disableFuture', 'shouldDisableTime-hours', 'shouldDisableTime-minutes' or 'shouldDisableTime-seconds', and null when the value is valid. Map it to your own errorMessage.

import dayjs, { type Dayjs } from 'dayjs';

const messages: Record<string, string> = {
  invalidDate: 'Enter a valid time',
  minTime: 'We open at 9:00',
  maxTime: 'We close at 17:00'
};

const [value, setValue] = useState<Dayjs | null>(null);
const [error, setError] = useState<string>();

<MUITimePicker
  fieldName="pickupTime"
  value={value}
  onValueChange={({ newValue, context }) => {
    setValue(newValue);
    setError(context.validationError ? messages[context.validationError] : undefined);
  }}
  minTime={dayjs().hour(9).minute(0)}
  maxTime={dayjs().hour(17).minute(0)}
  errorMessage={error}
/>

Customizing the input

format sets how the time is written in the field, using the tokens of your date library, such as 'HH:mm' for Day.js. slotProps.textField is forwarded to the text field, as an object or a function, for props like size and fullWidth. The component controls the text field's id, error and ARIA attributes.

<MUITimePicker
  fieldName="alarm"
  value={alarm}
  onValueChange={({ newValue }) => setAlarm(newValue)}
  format="HH:mm"
  slotProps={{ textField: { size: 'small', fullWidth: true } }}
/>

API

All four variants (MUITimePicker, MUIDesktopTimePicker, MUIMobileTimePicker, MUIStaticTimePicker) share the props below.

Props marked with * are required.

NameTypeDescription
fieldName*string
Name/path of the field. Used to derive the id, the default label, and the name attribute. This prop is required for all components.
valuePickerValidDate | null
Current picker value in the configured date library format. Pass null or undefined to clear the picker.
onValueChange*({ newValue, context }) => void
Called after the picker accepts a valid time value. context.validationError reports the MUI X validation status.
requiredboolean
Indicates that the field is mandatory by adding an asterisk symbol (*) to the form label and setting the relevant accessibility attributes.
labelReactNode
Label displayed for the field. Defaults to a human-readable label derived from fieldName, e.g. firstName becomes "First Name".
showLabelAboveFormFieldboolean
When true, renders the field label above the form field in the FormLabel component, instead of inside or beside it. Takes precedence over allLabelsAboveFields from the ConfigProvider, so false keeps the label inside this field even when the config places every label above its field.
formLabelPropsFormLabelProps
FormLabelProps forwarded to the internal FormLabel. The id is managed by the component. Multiple fields can be configured using the ConfigProvider component.
hideLabelboolean
When true, hides the rendered field label while preserving accessible labeling where possible.
errorMessagestring | string[]
Validation error for the field — pass a single message string, or a string[] when the field can fail multiple rules at once (every message is shown together). A non-empty string or array puts the field in an error state; undefined/''/[] clear it.
Normalize your form library's error shape to this at the call site (e.g. an RHF FieldError via its .message). Use renderError to customize how the message(s) are rendered.
renderError(errors: string[]) => ReactNode
Custom renderer for the resolved error message(s), called only when the field is in an error state. Always receives a string[] — use errors[0] for the common single-message case, or map over errors when a field fails several rules. By default a single message renders as text and multiple messages render on separate lines.
hideErrorMessageboolean
If true, hides the error message text while keeping the field in an error state.
helperTextReactNode
Content displayed in the FormHelperText component below the field when there is no visible validation error.
formHelperTextPropsFormHelperTextProps
FormHelperTextProps forwarded to the internal FormHelperText. The id is managed by the component. Multiple fields can be configured using the ConfigProvider component.
slotPropsobject
MUI X picker slotProps. The textField slot is merged with the component's own id, error state, and aria attributes.
customIds{ field, label, helperText, error }
Overrides the default field, label, helper text, and error IDs used for accessibility.
Info

MUIStaticTimePicker renders inline with no text field, so two props behave slightly differently: fieldName only derives the generated ids and default label (no name attribute, since there's no input), and showLabelAboveFormField defaults to false — with no built-in inline label, that means no visible label renders at all (the accessible name is still applied).

Playground

Time Pickers

MUITimePicker — responsive, 24-hour format

hh:mm

MUIDesktopTimePicker — always the keyboard-first UI

hh:mm aa

MUIMobileTimePicker — always the modal UI

hh:mm aa

MUIStaticTimePicker — always-visible inline, no text field

Select time
:
123456789101112

Form State - Values & Errors

Source Code

View the full implementation of this component on GitHub.