@hero-design/react-native-month-year-picker

Overview

A React Native library that provides native month and year picker components for iOS and Android. It includes platform-specific implementations (MonthYearPickerViewIOS for iOS, MonthYearPickerDialogueAndroid for Android), date range constraints, internationalization support, theme support (light/dark mode), and is used internally by @hero-design/rn Calendar and DatePicker components.

Installation

npm install @hero-design/react-native-month-year-picker
# or
yarn add @hero-design/react-native-month-year-picker

Peer Dependencies:

yarn add [email protected] [email protected]

Requirements:

• React 18.3.1
• React Native 0.77.3 (compatible with Hero Design)
• Node.js >= 20.0.0 (20.x or 22.x supported)
• Yarn >= 4.0.2 (enabled via Corepack: corepack enable)
• iOS Simulator (iPhone 14, iOS 18+) or Android Emulator (Pixel 6, API 30) for development

iOS Setup

After installing, you need to run pod install:

cd ios && pod install

Note: This package uses native modules and cannot be used with Expo Go. You must use a development build or bare React Native project.

Usage

iOS - MonthYearPickerViewIOS

The iOS component renders a native month/year picker view:

import { MonthYearPickerViewIOS } from '@hero-design/react-native-month-year-picker';

function MyDatePicker() {
  const [selectedDate, setSelectedDate] = useState(new Date());

  return (
    <MonthYearPickerViewIOS
      value={selectedDate}
      onChange={(date) => setSelectedDate(date)}
      minimumDate={new Date(2020, 0, 1)}
      maximumDate={new Date(2030, 11, 31)}
      locale="en"
      textColor="#000000"
      style={{ height: '100%', width: '100%' }}
    />
  );
}

Android - MonthYearPickerDialogueAndroid

The Android component displays a native dialog picker:

import { MonthYearPickerDialogueAndroid } from '@hero-design/react-native-month-year-picker';

function MyDatePicker() {
  const [selectedDate, setSelectedDate] = useState(new Date());

  return (
    <MonthYearPickerDialogueAndroid
      value={selectedDate}
      onChange={(action, date) => {
        if (action === 'dateSetAction' && date) {
          setSelectedDate(date);
        }
      }}
      minimumDate={new Date(2020, 0, 1)}
      maximumDate={new Date(2030, 11, 31)}
      doneButtonLabel="Done"
      cancelButtonLabel="Cancel"
      locale="en"
      themeVariant="light"
    />
  );
}

Platform-Specific Usage

For cross-platform usage, use Platform to conditionally render:

import { Platform } from 'react-native';
import {
  MonthYearPickerViewIOS,
  MonthYearPickerDialogueAndroid,
} from '@hero-design/react-native-month-year-picker';

function MonthYearPicker({ value, onChange, ...props }) {
  if (Platform.OS === 'ios') {
    return (
      <MonthYearPickerViewIOS
        value={value}
        onChange={onChange}
        {...props}
      />
    );
  }

  return (
    <MonthYearPickerDialogueAndroid
      value={value}
      onChange={onChange}
      {...props}
    />
  );
}

API Reference

MonthYearPickerViewIOS Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | value | Date | new Date() | Currently selected date | | onChange | (date: Date) => void | Required | Callback when date changes | | minimumDate | Date? | undefined | Minimum selectable date | | maximumDate | Date? | undefined | Maximum selectable date | | locale | string | 'en' | Locale for date formatting | | textColor | string? | undefined | Text color for the picker | | autoTheme | boolean | false | Automatically detect system theme | | style | ViewStyle? | undefined | Style for the container view |

MonthYearPickerDialogueAndroid Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | value | Date | new Date() | Currently selected date | | onChange | (action: string, date: Date \| undefined) => void | Required | Callback when dialog action occurs | | minimumDate | Date? | undefined | Minimum selectable date | | maximumDate | Date? | undefined | Maximum selectable date | | doneButtonLabel | string | 'Done' | Label for the done button | | cancelButtonLabel | string | 'Cancel' | Label for the cancel button | | locale | string | 'en' | Locale for date formatting | | themeVariant | 'light' \| 'dark' | undefined | Theme variant (ignored if autoTheme is true) | | autoTheme | boolean | false | Automatically detect system theme |

Action Types

For Android onChange callback, the action parameter can be:

• 'dateSetAction' - User confirmed the date selection
• 'dismissedAction' - User dismissed the dialog without selecting

Theming

iOS Theming

The iOS picker supports text color customization and automatic theme detection:

import { useTheme } from '@hero-design/rn';

function ThemedPicker() {
  const theme = useTheme();
  
  return (
    <MonthYearPickerViewIOS
      value={selectedDate}
      onChange={setSelectedDate}
      textColor={theme.colors.onDefaultGlobalSurface}
      autoTheme={true}
    />
  );
}

Android Theming

The Android picker supports light/dark theme variants:

import { useTheme } from '@hero-design/rn';

function ThemedPicker() {
  const theme = useTheme();
  
  return (
    <MonthYearPickerDialogueAndroid
      value={selectedDate}
      onChange={handleChange}
      themeVariant={theme.themeMode === 'dark' ? 'dark' : 'light'}
      autoTheme={true}
    />
  );
}

Note: When autoTheme is set to true, the themeVariant prop is ignored and the system theme is automatically detected.

Examples

Integration with Calendar Component

This picker is used internally by the @hero-design/rn Calendar component:

import Calendar from '@hero-design/rn';

function MyCalendar() {
  return (
    <Calendar
      value={selectedDate}
      onChange={setSelectedDate}
      onToggleMonthPicker={(visible) => {
        // Month picker visibility is handled internally
      }}
      monthPickerConfirmLabel="Done"
      monthPickerCancelLabel="Cancel"
    />
  );
}

Integration with DatePicker Component

Used in DatePicker for month-year selection variant:

import { DatePicker } from '@hero-design/rn';

function MyDatePicker() {
  return (
    <DatePicker
      value={selectedDate}
      onChange={setSelectedDate}
      variant="month-year"
      label="Select Month & Year"
    />
  );
}

Custom Dialog Implementation

Example of wrapping the Android picker in a custom dialog:

import { useState } from 'react';
import { Button } from '@hero-design/rn';
import { MonthYearPickerDialogueAndroid } from '@hero-design/react-native-month-year-picker';

function CustomMonthPicker() {
  const [date, setDate] = useState(new Date());
  const [visible, setVisible] = useState(false);

  return (
    <>
      <Button text="Select Month/Year" onPress={() => setVisible(true)} />
      {visible && (
        <MonthYearPickerDialogueAndroid
          value={date}
          onChange={(action, newDate) => {
            if (action === 'dateSetAction' && newDate) {
              setDate(newDate);
            }
            setVisible(false);
          }}
          doneButtonLabel="Confirm"
          cancelButtonLabel="Cancel"
        />
      )}
    </>
  );
}

Contributing

Contributions to @hero-design/react-native-month-year-picker are welcome!

To get started:

1. Clone the repository: git clone [email protected]:Thinkei/hero-design.git
2. Enable Corepack: corepack enable
3. Install dependencies: yarn install
4. Bootstrap the example app: yarn workspace @hero-design/react-native-month-year-picker bootstrap
5. Build the package: yarn turbo run build --filter=@hero-design/react-native-month-year-picker

For detailed contributing guidelines, see CONTRIBUTING.md.

License

MIT

Made with react-native-builder-bob