@dooherceg/mui-date-range-picker

Reusable date range picker components for MUI built on top of @mui/x-date-pickers.

npm version

• Latest package: https://www.npmjs.com/package/@dooherceg/mui-date-range-picker
• Install command: npm install @dooherceg/mui-date-range-picker

Features

• DateRangePicker for date-only range selection
• DateTimeRangePicker for date and time range selection
• Controlled and uncontrolled usage
• Range preview while selecting the second boundary
• MUI TextField styling support through variant, size, className, and sx
• TypeScript types exported with the package

Installation

Install the package together with its peer dependencies:

npm install @dooherceg/mui-date-range-picker @mui/material @mui/x-date-pickers @emotion/react @emotion/styled dayjs react react-dom

Required setup

This package expects Dayjs-compatible values at runtime, so wrap your application, page, or story with MUI LocalizationProvider and AdapterDayjs.

import { LocalizationProvider } from "@mui/x-date-pickers/LocalizationProvider";
import { AdapterDayjs } from "@mui/x-date-pickers/AdapterDayjs";

export const AppProviders = ({ children }: { children: React.ReactNode }) => {
  return (
    <LocalizationProvider dateAdapter={AdapterDayjs}>
      {children}
    </LocalizationProvider>
  );
};

Exports

The package exports:

• DateRangePicker
• DateTimeRangePicker
• DateRangeValue
• BaseRangePickerProps
• DateRangePickerProps
• DateTimeRangePickerProps
• DateTimeRangePickerTranslations

Quick start

DateRangePicker

import { useState } from "react";
import type { Dayjs } from "dayjs";
import {
  DateRangePicker,
  type DateRangeValue,
} from "@dooherceg/mui-date-range-picker";

export const DateRangeExample = () => {
  const [value, setValue] = useState<DateRangeValue<Dayjs>>({
    start: null,
    end: null,
  });

  return (
    <DateRangePicker
      value={value}
      onChange={setValue}
      format="DD/MM/YYYY"
      placeholder="Select date"
      separator=" - "
    />
  );
};

DateTimeRangePicker

import { useState } from "react";
import type { Dayjs } from "dayjs";
import {
  DateTimeRangePicker,
  type DateRangeValue,
} from "@dooherceg/mui-date-range-picker";

export const DateTimeRangeExample = () => {
  const [value, setValue] = useState<DateRangeValue<Dayjs>>({
    start: null,
    end: null,
  });

  return (
    <DateTimeRangePicker
      value={value}
      onChange={setValue}
      format="DD/MM/YYYY HH:mm"
      placeholder="Select date and time"
      translations={{
        prev: "Prev",
        next: "Next",
        selecting: "Selecting",
        from: "From",
        to: "To",
      }}
      timeSteps={{ hours: 1, minutes: 5 }}
    />
  );
};

Controlled and uncontrolled usage

Controlled usage:

<DateRangePicker value={value} onChange={setValue} />

Uncontrolled usage:

<DateRangePicker
  defaultValue={{ start: null, end: null }}
  onChange={(nextValue) => {
    console.log(nextValue);
  }}
/>

Shared types

import type {
  DateRangeValue,
  DateRangePickerProps,
  DateTimeRangePickerProps,
  DateTimeRangePickerTranslations,
} from "@dooherceg/mui-date-range-picker";

DateRangeValue

type DateRangeValue<TDate> = {
  start: TDate | null;
  end: TDate | null;
};

DateRangePicker props

| Prop | Type | Default | Description | | -------------- | --------------------------------- | ---------------------------- | ----------------------------------------------- | | value | DateRangeValue | undefined | Controlled range value. | | defaultValue | DateRangeValue | { start: null, end: null } | Initial value for uncontrolled usage. | | onChange | (value: DateRangeValue) => void | undefined | Called when the committed range changes. | | disabled | boolean | false | Disables the input and picker interactions. | | readOnly | boolean | false | Keeps the value visible but blocks interaction. | | minDate | PickerValidDate | undefined | Lower date boundary. | | maxDate | PickerValidDate | undefined | Upper date boundary. | | format | string | DD/MM/YYYY | Display format used in the input. | | placeholder | string | format | Placeholder used for empty boundaries. | | separator | string | - | Text rendered between start and end values. | | className | string | undefined | Class applied to the input root. | | sx | SxProps<Theme> | undefined | MUI system styles for the input root. | | variant | TextFieldProps["variant"] | outlined | MUI text field variant. | | size | TextFieldProps["size"] | small | MUI text field size. | | name | string | undefined | Name forwarded to the underlying input. |

DateTimeRangePicker props

DateTimeRangePicker supports all shared props above and adds:

| Prop | Type | Default | Description | | -------------- | ------------------------------------------ | -------------------------- | --------------------------------- | | translations | Partial<DateTimeRangePickerTranslations> | English defaults | Labels used in the toolbar. | | timeSteps | { hours?: number; minutes?: number } | { hours: 1, minutes: 1 } | Clock step configuration. | | format | string | DD/MM/YYYY HH:mm | Display format used in the input. |

DateTimeRangePickerTranslations

type DateTimeRangePickerTranslations = {
  prev: string;
  next: string;
  selecting: string;
  from: string;
  to: string;
};

Behavior notes

• DateRangePicker shows an outline preview while the second date is being selected.
• DateTimeRangePicker shows that preview only while the end boundary is active.
• DateTimeRangePicker preserves the existing time when the date changes.
• DateTimeRangePicker preserves the existing date when the time changes.
• Both pickers normalize reversed selections into a valid range.
• Both pickers render a read-only input and use the popup picker UI for changes.

Styling

Both components render a MUI TextField, so they fit naturally into an existing MUI design system.

<DateRangePicker variant="outlined" size="small" sx={{ minWidth: 320 }} />

License

MIT