MaskedDateInput

Masked date input with individual fields for day, month and year

Usage

MaskedDateInput is similar to TimePicker but for dates. It renders masked fields for day, month and year with an optional calendar dropdown:

//
import { MaskedDateInput } from '@mantine/dates';

function Demo() {
  return <MaskedDateInput label="Date of birth" />;
}

MaskedDateInput with uncontrolled forms

Set name to submit a complete date, including the time if withTime is set. An incomplete or empty date submits an empty string:

import { MaskedDateInput } from '@mantine/dates';

function Demo() {
  return (
    <form
      onSubmit={(event) => {
        event.preventDefault();
        const data = new FormData(event.currentTarget);
        console.log(data.get('birthday'));
      }}
    >
      <MaskedDateInput
        name="birthday"
        label="Birthday"
        defaultValue="2025-05-12"
      />
      <button type="submit">Submit</button>
    </form>
  );
}

Controlled

The value is a string in YYYY-MM-DD format, or YYYY-MM-DD HH:mm:ss when withTime is set. null represents no value. onChange is called when all fields are filled or when all fields are cleared:

//
null
import { useState } from 'react';
import { Code } from '@mantine/core';
import { MaskedDateInput } from '@mantine/dates';

function Demo() {
  const [value, setValue] = useState<string | null>(null);

  return (
    <>
      <MaskedDateInput label="Date of birth" value={value} onChange={setValue} />
      <Code block mt="md">
        {value ?? 'null'}
      </Code>
    </>
  );
}

With time

Set the withTime prop to display hours and minutes fields in addition to date fields:

// :
import { MaskedDateInput } from '@mantine/dates';

function Demo() {
  return <MaskedDateInput label="Date and time" withTime />;
}

With seconds

Set the withSeconds prop to display the seconds field, withTime must also be set:

// ::
import { MaskedDateInput } from '@mantine/dates';

function Demo() {
  return <MaskedDateInput label="Date and time" withTime withSeconds />;
}

12-hour format

Set format="12h" to use 12-hour time format with an am/pm selector:

// :
import { MaskedDateInput } from '@mantine/dates';

function Demo() {
  return <MaskedDateInput label="Date and time" withTime format="12h" />;
}

Change am/pm labels

Use the amPmLabels prop to customize am/pm labels:

// :
import { MaskedDateInput } from '@mantine/dates';

function Demo() {
  return (
    <MaskedDateInput
      label="Date and time"
      withTime
      format="12h"
      amPmLabels={{ am: 'पू', pm: 'अ' }}
    />
  );
}

Date separator

Use the dateSeparator prop to change the separator displayed between date fields:

..
--
/ /
import { Stack } from '@mantine/core';
import { MaskedDateInput } from '@mantine/dates';

function Demo() {
  return (
    <Stack>
      <MaskedDateInput label="Dot separator" dateSeparator="." />
      <MaskedDateInput label="Dash separator" dateSeparator="-" />
      <MaskedDateInput label="Spaced slash separator" dateSeparator=" / " />
    </Stack>
  );
}

Time separator

Use the timeSeparator prop to change the separator displayed between time fields:

// .
import { MaskedDateInput } from '@mantine/dates';

function Demo() {
  return <MaskedDateInput label="Date and time" withTime timeSeparator="." />;
}

Fields order

Use the fieldsOrder prop to change the order of day, month and year fields:

//
//
//
import { Stack } from '@mantine/core';
import { MaskedDateInput } from '@mantine/dates';

function Demo() {
  return (
    <Stack>
      <MaskedDateInput label="Day / Month / Year (default)" fieldsOrder={['day', 'month', 'year']} />
      <MaskedDateInput label="Month / Day / Year" fieldsOrder={['month', 'day', 'year']} />
      <MaskedDateInput label="Year / Month / Day" fieldsOrder={['year', 'month', 'day']} />
    </Stack>
  );
}

Min and max dates

Set minDate and maxDate to restrict the date range. An out-of-range date is clamped to the nearest valid date when the input loses focus:

//
import { MaskedDateInput } from '@mantine/dates';

function Demo() {
  return (
    <MaskedDateInput
      label="Date of birth"
      minDate="1924-01-01"
      maxDate="2024-12-31"
    />
  );
}

Allow deselect

Set the allowDeselect prop to allow clearing the value by clicking the selected date in the calendar dropdown:

//
import { MaskedDateInput } from '@mantine/dates';

function Demo() {
  return (
    <MaskedDateInput
      label="Date of birth"
      defaultValue="2000-06-15"
      allowDeselect
    />
  );
}

Without dropdown

Set withDropdown={false} to disable the calendar dropdown:

//
import { MaskedDateInput } from '@mantine/dates';

function Demo() {
  return <MaskedDateInput label="Date of birth" withDropdown={false} />;
}

Dropdown position

Use popoverProps to pass props down to the underlying Popover component, for example to display the dropdown above the input. The dropdown scrolls when it does not fit in the viewport, pass middlewares: { size: false } to disable this behavior:

//
import { MaskedDateInput } from '@mantine/dates';

function Demo() {
  return (
    <MaskedDateInput
      label="Date of birth"
      popoverProps={{
        position: 'top-start',
        middlewares: { flip: false, shift: false, size: false },
      }}
    />
  );
}

Hours/minutes/seconds step

Use hoursStep, minutesStep and secondsStep props to change the arrow keys step of time fields:

// ::
import { MaskedDateInput } from '@mantine/dates';

function Demo() {
  return (
    <MaskedDateInput
      label="Date and time"
      withTime
      withSeconds
      hoursStep={1}
      minutesStep={5}
      secondsStep={10}
    />
  );
}

Paste events

By default, MaskedDateInput handles pasted ISO dates and date-times. Use pasteSplit to parse other formats:

//

Try pasting a date in DD.MM.YYYY format. For example, try pasting 15.06.2000

import { Code, Text } from '@mantine/core';
import { MaskedDateInput } from '@mantine/dates';

const re = /^(\d{1,2})\.(\d{1,2})\.(\d{4})$/;

const customPasteSplit = (value: string) => {
  const match = value.match(re);
  if (!match) {
    return { day: null, month: null, year: null };
  }

  return {
    day: Number(match[1]),
    month: Number(match[2]),
    year: Number(match[3]),
  };
};

function Demo() {
  return (
    <div>
      <MaskedDateInput label="Paste date here" pasteSplit={customPasteSplit} />
      <Text mt="md">
        Try pasting a date in DD.MM.YYYY format. For example, try pasting{' '}
        <Code>15.06.2000</Code>
      </Text>
    </div>
  );
}

Controlling with useMaskedDateInput

MaskedDateInput component supports the controller pattern. Use the useMaskedDateInput hook to manage MaskedDateInput state. When the controller prop is set, the value, time, format and date limit props of the component are ignored, pass them to useMaskedDateInput instead:

//

Value: null, day: null, month: null, year: null

import { Button, Code, Group, Stack, Text } from '@mantine/core';
import { MaskedDateInput, useMaskedDateInput } from '@mantine/dates';

function Demo() {
  const controller = useMaskedDateInput();

  return (
    <Stack>
      <MaskedDateInput label="Date of birth" controller={controller} withDropdown={false} />

      <Text size="sm">
        Value: <Code>{controller.getValue() || 'null'}</Code>, day: <Code>{String(controller.getDay())}</Code>,
        month: <Code>{String(controller.getMonth())}</Code>, year: <Code>{String(controller.getYear())}</Code>
      </Text>

      <Group>
        <Button variant="default" onClick={() => controller.setValue('1990-06-15')}>
          Set 1990-06-15
        </Button>
        <Button variant="default" onClick={() => controller.focus('year')}>
          Focus year
        </Button>
        <Button variant="default" onClick={controller.clear} disabled={!controller.hasValue()}>
          Clear
        </Button>
      </Group>
    </Stack>
  );
}

useMaskedDateInput accepts the state options that MaskedDateInput accepts as props, and returns actions and queries:

import { MaskedDateInput, useMaskedDateInput } from '@mantine/dates';

function Demo() {
  const controller = useMaskedDateInput({
    defaultValue: '2024-03-15', // -> uncontrolled initial value
    // value, onChange -> controlled state, same as on MaskedDateInput
    // withTime, withSeconds, format, amPmLabels, minDate, maxDate, pasteSplit -> same as on MaskedDateInput
  });

  // Actions
  controller.setValue('2024-03-15'); // -> sets all fields, a date without time keeps the time fields
  controller.setValue(null); // -> clears all fields
  controller.setDay(15);
  controller.setMonth(3); // -> 1-12
  controller.setYear(2024);
  controller.setHours(14);
  controller.setMinutes(30);
  controller.setSeconds(0);
  controller.setAmPm('pm'); // -> 'am' | 'pm' | null
  controller.clear(); // -> clears all fields and focuses the first field of fieldsOrder
  controller.focus('year'); // -> 'day' | 'month' | 'year' | 'hours' | 'minutes' | 'seconds' | 'amPm'

  // Queries
  controller.getValue(); // -> complete value, null if it is not complete or outside of minDate/maxDate
  controller.getDay(); // -> number | null
  controller.getMonth(); // -> number | null
  controller.getYear(); // -> number | null
  controller.getHours(); // -> number | null
  controller.getMinutes(); // -> number | null
  controller.getSeconds(); // -> number | null
  controller.getAmPm(); // -> 'am' | 'pm' | null, always null in 24h format
  controller.hasValue(); // -> boolean, true if at least one field has a value

  return <MaskedDateInput controller={controller} />;
}

Usage with forms

A controller and form.getInputProps() cannot be spread on the same component: the controller ignores value and onChange. Instead, wrap MaskedDateInput in a component that owns the controller and bind the form to that component, see the controllers guide. A partially entered date is null for the form, use controller.hasValue() and the field queries to report it with a specific message:

//

Submitted value: none

import { useState } from 'react';
import { Button, Code, Group, Stack, Text } from '@mantine/core';
import { MaskedDateInput, MaskedDateInputProps, useMaskedDateInput } from '@mantine/dates';
import { useForm } from '@mantine/form';

function DateField({
  value,
  defaultValue,
  onChange,
  withTime,
  withSeconds,
  format,
  amPmLabels,
  minDate,
  maxDate,
  pasteSplit,
  error,
  ...others
}: Omit<MaskedDateInputProps, 'controller'>) {
  const controller = useMaskedDateInput({
    value,
    defaultValue,
    onChange,
    withTime,
    withSeconds,
    format,
    amPmLabels,
    minDate,
    maxDate,
    pasteSplit,
  });
  const dateFieldsFilled =
    controller.getDay() !== null &&
    controller.getMonth() !== null &&
    (controller.getYear() ?? 0) >= 1000;
  const entryError = dateFieldsFilled
    ? 'Date is outside of the allowed range'
    : 'Finish entering the date';

  return (
    <MaskedDateInput
      controller={controller}
      error={error && controller.hasValue() ? entryError : error}
      {...others}
    />
  );
}

function Demo() {
  const [submitted, setSubmitted] = useState<string | null>(null);
  const form = useForm({
    initialValues: { birthday: null as string | null },
    validate: { birthday: (value) => (value ? null : 'Date of birth is required') },
  });

  return (
    <form onSubmit={form.onSubmit((values) => setSubmitted(values.birthday))}>
      <Stack>
        <DateField
          label="Date of birth"
          minDate="1924-01-01"
          maxDate="2024-12-31"
          withDropdown={false}
          {...form.getInputProps('birthday')}
        />

        <Text size="sm">
          Submitted value: <Code>{submitted ?? 'none'}</Code>
        </Text>

        <Group>
          <Button type="submit">Submit</Button>
          <Button variant="default" onClick={() => form.setFieldValue('birthday', '1990-06-15')}>
            Set 1990-06-15
          </Button>
          <Button variant="default" onClick={form.reset}>
            Reset
          </Button>
        </Group>
      </Stack>
    </form>
  );
}

Clearable

Set the clearable prop to display a clear button in the right section of the input:

//
import { MaskedDateInput } from '@mantine/dates';

function Demo() {
  return <MaskedDateInput label="Date of birth" clearable defaultValue="2000-06-15" />;
}

Clear section mode

The clearSectionMode prop determines how the clear button and rightSection are rendered:

  • 'both' (default) – render both the clear button and rightSection
  • 'rightSection' – render only the user-supplied rightSection, ignore clear button
  • 'clear' – render only the clear button, ignore rightSection
//
//
//
import { CaretDownIcon } from '@phosphor-icons/react';
import { Stack } from '@mantine/core';
import { MaskedDateInput } from '@mantine/dates';

function Demo() {
  return (
    <Stack>
      <MaskedDateInput
        label="clearSectionMode='both' (default)"
        defaultValue="2000-06-15"
        clearable
        rightSection={<CaretDownIcon size={16} />}
        clearSectionMode="both"
      />

      <MaskedDateInput
        label="clearSectionMode='rightSection'"
        defaultValue="2000-06-15"
        clearable
        rightSection={<CaretDownIcon size={16} />}
        clearSectionMode="rightSection"
      />

      <MaskedDateInput
        label="clearSectionMode='clear'"
        defaultValue="2000-06-15"
        clearable
        rightSection={<CaretDownIcon size={16} />}
        clearSectionMode="clear"
      />
    </Stack>
  );
}

Disabled

//
import { MaskedDateInput } from '@mantine/dates';

function Demo() {
  return <MaskedDateInput label="Date of birth" disabled />;
}

Read only

//
import { MaskedDateInput } from '@mantine/dates';

function Demo() {
  return <MaskedDateInput label="Date of birth" defaultValue="2000-06-15" readOnly />;
}

Input props

MaskedDateInput component supports Input and Input.Wrapper component features and all div element props. The MaskedDateInput documentation does not include all features supported by the component – see the Input documentation to learn about all available features.

Input description

//
Variant
Size
Radius
import { MaskedDateInput } from '@mantine/dates';

function Demo() {
  return (
    <MaskedDateInput
      label="Input label"
      description="Input description"
    />
  );
}

Get refs

Every field has a ref prop, for example dayRef or hoursRef, to get the ref of its input:

import { useRef } from 'react';
import { MaskedDateInput } from '@mantine/dates';

function Demo() {
  const dayRef = useRef<HTMLInputElement>(null);
  const monthRef = useRef<HTMLInputElement>(null);
  const yearRef = useRef<HTMLInputElement>(null);

  return (
    <MaskedDateInput
      dayRef={dayRef}
      monthRef={monthRef}
      yearRef={yearRef}
    />
  );
}

onFocus and onBlur

onFocus is called when one of the inputs receives focus and onBlur is called when focus leaves all inputs:

import { MaskedDateInput } from '@mantine/dates';

function Demo() {
  return (
    <MaskedDateInput
      onFocus={() => console.log('Focused')}
      onBlur={() => console.log('Blurred')}
    />
  );
}

Accessibility

Each field has an English aria-label by default. Use the corresponding props to translate the labels. If clearable is set, also label the clear button:

import { MaskedDateInput } from '@mantine/dates';

function Demo() {
  return (
    <MaskedDateInput
      label="Fecha de nacimiento"
      dayInputLabel="Día"
      monthInputLabel="Mes"
      yearInputLabel="Año"
      clearButtonProps={{ 'aria-label': 'Borrar fecha' }}
    />
  );
}

Keyboard interactions:

KeyDescription
ArrowDownDecrements current value by step
ArrowUpIncrements current value by step
HomeSets current value to min possible value
EndSets current value to max possible value
BackspaceClears current value
ArrowRightMoves focus to the next input
ArrowLeftMoves focus to the previous input