react-native-ui-datepicker

If you want to clear the existing starter code and begin with a blank project, run the following command. This will move the current starter code to the app-example directory and create a fresh, empty app directory.

npm run reset-project

To use the component, import DateTimePicker, DateType, and useDefaultStyles. You must specify a mode (single, range, or multiple) and provide an onChange handler to manage the selected date state.

import { useState } from  'react';
import DateTimePicker, { DateType, useDefaultStyles } from 'react-native-ui-datepicker';

export function Calendar() {
  const defaultStyles = useDefaultStyles();
  const [selected, setSelected] = useState<DateType>();

  return (
    <DateTimePicker
      mode="single"
      date={selected}
      onChange={({ date }) =>  setSelected(date)}
      styles={defaultStyles}
    />
  );
}

To run the included demo application, install the dependencies and start the Expo development server using the following commands:

1. Install dependencies:

   npm install

2. Start the app:

   npx expo start

You can then open the app in a development build, Android emulator, iOS simulator, or Expo Go.

You can install the package using npm or yarn to add the customizable DateTimePicker to your React Native project.

npm install react-native-ui-datepicker

Or

yarn add react-native-ui-datepicker

Use the components prop to replace default calendar elements with your own custom components. This allows for deep UI customization of days, months, years, and more.

To implement this, create a CalendarComponents object containing your custom components and pass it to the DateTimePicker.

import DateTimePicker, {
  CalendarDay,
  CalendarMonth,
  CalendarComponents,
} from 'react-native-ui-datepicker';

const components: CalendarComponents = {
  Day: (day: CalendarDay) => <YourCustomDay day={day} />,
  Month: (month: CalendarMonth) => <YourCustomMonth month={month} />
  // etc
};

export function Calendar() {
  return (
      <DateTimePicker
        components={components}
      />
  );
}

The library provides built-in support for the Jalali (Persian) calendar. It includes specific month names for both English (en) and Persian (fa) locales. Use isValidJalaliLocale to verify if a locale is supported for Jalali features.

import { isValidJalaliLocale } from 'react-native-ui-datepicker/src/utils';

const isSupported = isValidJalaliLocale('fa'); // true

If your project uses NativeWind, use the classNames prop to apply Tailwind CSS classes. Use useDefaultClassNames() to get the base classes and override them as needed.

import DateTimePicker, { useDefaultClassNames } from 'react-native-ui-datepicker';

export function Calendar() {
  const defaultClassNames = useDefaultClassNames();

  return (
    <DateTimePicker
      classNames={{
        ...defaultClassNames,
        today: 'border-amber-500',
        selected: 'bg-amber-500 border-amber-500',
        selected_label: "text-white",
        day: `${defaultClassNames.day} hover:bg-amber-100`,
        disabled: 'opacity-50',
      }}
    />
  );
}

You can customize the component's appearance using the styles prop. It is recommended to use useDefaultStyles() and spread it into your custom object to ensure you only override specific parts. Styles are mapped to the UI Theme enums.

import DateTimePicker, { useDefaultStyles } from 'react-native-ui-datepicker';

export function Calendar() {
  const defaultStyles = useDefaultStyles();

  return (
    <DateTimePicker
      styles={{
        ...defaultStyles,
        today: { borderColor: 'blue', borderWidth: 1 }, // Add a border to today's date
        selected: { backgroundColor: 'blue' }, // Highlight the selected day
        selected_label: { color: 'white' }, // Highlight the selected day label
      }}
    />
  );
}

Use the timeZone prop to define the timezone for the DateTimePicker. You can provide either an IANA time zone identifier or a UTC offset.

<DateTimePicker timeZone="UTC" /> // Use Coordinated Universal Time
<DateTimePicker timeZone="Asia/Tokyo" /> // Use Japan Standard Time (JST)

You can customize the language and numeral system of the calendar using the locale and numerals props.

• locale: A string defining the locale (defaults to en).
• numerals: Specifies the numeral system to use (e.g., latn, arab, arabext).

You can customize the calendar system, locale, and numbering system using the following props:

• calendar: The calendar system to use. Supports 'gregory' (default) and 'jalali' (Persian).
• locale: The locale string (e.g., 'en', 'fa') used for formatting.
• numerals: The numbering system (e.g., 'latn' for Latin/Western digits, or others supported by dayjs).
• timeZone: Sets the timezone for date calculations. When the timeZone changes, the component updates the current date to the new timezone.
• firstDayOfWeek: An integer (0-6) representing the first day of the week (0 is typically Sunday).

When mode="single" is used, these props control the single date selection and time picker behavior:

| Name         | Type               | Description                                                   |
| ------------ | ------------------ | ------------------------------------------------------------- |
| `date`       | `DateType`         | Specifies the currently selected date.                        |
| `onChange`   | `({date}) => void` | Callback function triggered when the date change.             |
| `timePicker` | `boolean`          | Whether to enable the time picker.                          |
| `use12Hours` | `boolean`          | Whether to use a 12-hour format (AM/PM) in the time picker.  |