Date-Time Pickers
These components wrap the Material UI X Date-time Picker with the suite's label, error and helper-text handling.
Use a date-time picker when something needs both a day and a time, such as a meeting, a flight departure or a delivery slot. A single field captures both, so you don't have to keep a separate date and time in sync.
Each comes in four variants that share the same controlled contract — a value
in your date library's format and an onValueChange callback:
MUIDateTimePicker— responsive (renders the desktop UI on pointer devices, the mobile UI on touch).MUIDesktopDateTimePicker— always renders the desktop (keyboard-first) UI.MUIMobileDateTimePicker— always renders the mobile (modal) UI.MUIStaticDateTimePicker— an always-visible inline picker with no text field.
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>Without a dateAdapter, the pickers throw at render — this is the
one required piece of setup.
Usage
import { MUIDateTimePicker } from '@nish1896/mui-components/mui-pickers/date-time';
import { type Dayjs } from 'dayjs';const [value, setValue] = useState<Dayjs | null>(null);
<MUIDateTimePicker
fieldName="datetime"
value={value}
onValueChange={({ newValue, context }) => setValue(newValue)}
/>value uses the date type of your date adapter, such as a Dayjs for
AdapterDayjs, 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 dates and 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 MUIDesktopDateTimePicker for the keyboard-first popover
on every device, MUIMobileDateTimePicker for a modal dialog, and
MUIStaticDateTimePicker for an always-visible picker without a text
field (see the note below the API table).
import {
MUIDesktopDateTimePicker,
MUIMobileDateTimePicker,
MUIStaticDateTimePicker
} from '@nish1896/mui-components/mui-pickers/date-time';
<MUIMobileDateTimePicker
fieldName="meeting"
value={value}
onValueChange={({ newValue }) => setValue(newValue)}
/>onAccept is passed through to MUI X and fires when the user
finishes picking a value.
Validation and limits
Limit the selectable values with the MUI X props minDateTime,
maxDateTime, disablePast and disableFuture, or limit the
date and the time separately with minDate, maxDate, minTime
and maxTime.
Disabled values can't be picked, and a typed value outside the
limits is reported through context.validationError. It combines
the date and time errors, such as 'invalidDate', 'minDate',
'maxDate', 'minTime', 'maxTime', 'disablePast' and
'disableFuture', and is 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 date and time',
minDate: 'Pick a later date',
disablePast: 'Pick a time in the future'
};
const [value, setValue] = useState<Dayjs | null>(null);
const [error, setError] = useState<string>();
<MUIDateTimePicker
fieldName="meeting"
value={value}
onValueChange={({ newValue, context }) => {
setValue(newValue);
setError(context.validationError ? messages[context.validationError] : undefined);
}}
disablePast
errorMessage={error}
/>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.
Customizing the input
format sets how the value is written in the field, using the tokens
of your date library, such as 'DD/MM/YYYY 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.
<MUIDateTimePicker
fieldName="meeting"
value={value}
onValueChange={({ newValue }) => setValue(newValue)}
format="DD/MM/YYYY HH:mm"
ampm={false}
slotProps={{ textField: { size: 'small', fullWidth: true } }}
/>API
All four variants (MUIDateTimePicker, MUIDesktopDateTimePicker,
MUIMobileDateTimePicker, MUIStaticDateTimePicker) share the props below.
Props marked with * are required.
| Name | Type | Description |
|---|---|---|
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. |
value | PickerValidDate | 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 date-time value. context.validationError reports the MUI X validation status. |
required | boolean | Indicates that the field is mandatory by adding an asterisk symbol (*) to the form label and setting the relevant accessibility attributes. |
label | ReactNode | Label displayed for the field. Defaults to a human-readable label derived from fieldName, e.g. firstName becomes "First Name". |
showLabelAboveFormField | boolean | 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. |
formLabelProps | FormLabelProps | FormLabelProps forwarded to the internal FormLabel. The id is managed by the component. Multiple fields can be configured using the ConfigProvider component. |
hideLabel | boolean | When true, hides the rendered field label while preserving accessible labeling where possible. |
errorMessage | string | 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. |
hideErrorMessage | boolean | If true, hides the error message text while keeping the field in an error state. |
helperText | ReactNode | Content displayed in the FormHelperText component below the field when there is no visible validation error. |
formHelperTextProps | FormHelperTextProps | FormHelperTextProps forwarded to the internal FormHelperText. The id is managed by the component. Multiple fields can be configured using the ConfigProvider component. |
slotProps | object | 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. |
MUIStaticDateTimePicker 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
Date-Time Pickers
Source Code
View the full implementation of this component on GitHub.