rc-component-picker

Install the picker component via npm. Note that you must also install a date library (such as dayjs) to use it.

npm install @rc-component/picker

If you haven't installed a date library yet, install one (e.g., dayjs):

npm install dayjs

When using a picker in datetime or time mode, you can control the visibility of time components (hours, minutes, seconds, milliseconds) using the showTime prop.

showTime can be a boolean or a configuration object of type SharedTimeProps. If provided as an object, it allows fine-grained control over time-related settings such as steps, disabled ranges, and visibility. The component automatically infers visibility from the format string if explicit showXXX props are not provided.

// Example of passing time configuration
<Picker
  picker="datetime"
  showTime={{
    showHour: true,
    showMinute: true,
    showSecond: false,
    hourStep: 1,
    minuteStep: 5,
  }}
/>

The PickerPanel manages two distinct types of values:

1. Real Value (value/onChange): This is the actual selection made by the user. It is triggered when the user selects a value in the current picker mode.
2. Calendar Value (pickerValue/onPickerValueChange): This is a temporary value used to control which date/month/year is currently being viewed in the panel, without necessarily selecting it as the final value.

When a user selects a date in a mode that is not the final picker mode (e.g., selecting a year while in year mode to move to month mode), the component automatically transitions the mode to the next logical step in the hierarchy (e.g., year $\rightarrow$ month $\rightarrow$ date).

When you use the pickerValue prop to control the date displayed in the popup panel, you must also provide the onPickerValueChange callback to keep the component state in sync. This is useful for custom navigation or external controls of the calendar view.

onPickerValueChange provides the new date and an info object containing the source ('reset' or 'panel') and the next mode for both start and end panels.

<RangePicker
  pickerValue={currentPanelDate}
  onPickerValueChange={(date, info) => {
    // date: [Date, Date]
    // info.source: 'reset' | 'panel'
    // info.mode: [PanelMode, PanelMode]
    setCurrentPanelDate(date);
  }}
/>

The Picker component is used for selecting a single date or time value. It requires a generateConfig adapter (to bridge the component with your chosen date library) and a locale object.

Note: You must import the component's CSS for correct styling.

import type { Dayjs } from 'dayjs';
import dayjs from 'dayjs';
import Picker from '@rc-component/picker';
import dayjsGenerateConfig from '@rc-component/picker/generate/dayjs';
import enUS from '@rc-component/picker/locale/en_US';
import '@rc-component/picker/assets/index.css';

export default () => (
  <Picker<Dayjs> generateConfig={dayjsGenerateConfig} locale={enUS} defaultValue={dayjs()} />
);

The range demo showcases the usage of the RangePicker component. You can find the implementation details and usage patterns in the source file located at ../examples/range.tsx relative to this documentation file.

// See implementation in ../examples/range.tsx

The RangePicker allows selecting a start and end date/time. You can enable time selection via showTime and define quick-selection presets.

Example using dayjs:

import type { Dayjs } from 'dayjs';
import { RangePicker } from '@rc-component/picker';
import dayjsGenerateConfig from '@rc-component/picker/generate/dayjs';
import enUS from '@rc-component/picker/locale/en_US';

export default () => (
  <RangePicker<Dayjs>
    generateConfig={dayjsGenerateConfig}
    locale={enUS}
    showTime
    presets={[
      {
        label: 'Today',
        value: () => [dayjsGenerateConfig.getNow(), dayjsGenerateConfig.getNow()],
      },
    ]}
  />
);

The RangePicker component is used for selecting a start and end date/time range. It supports features like showTime for time selection and presets for quick selection of common ranges.

import type { Dayjs } from 'dayjs';
import { RangePicker } from '@rc-component/picker';
import dayjsGenerateConfig from '@rc-component/picker/generate/dayjs';
import enUS from '@rc-component/picker/locale/en_US';

export default () => (
  <RangePicker<Dayjs>
    generateConfig={dayjsGenerateConfig}
    locale={enUS}
    showTime
    presets={[
      {
        label: 'Today',
        value: () => [dayjsGenerateConfig.getNow(), dayjsGenerateConfig.getNow()],
      },
    ]}
  />
);

You can restrict the selection of certain dates in the Picker component by providing a disabledDate prop. The disabledDate prop accepts a function that receives a date object and returns a boolean: true if the date should be disabled, and false otherwise.

This is commonly used to prevent users from selecting past dates, future dates, or specific ranges of dates.

// Example logic for disabling past dates
const disabledDate = (current: Dayjs | null) => {
  return current && current < dayjs().startOf('day');
};

<Picker
  disabledDate={disabledDate}
/>

To use the Picker component, you must provide a generateConfig adapter corresponding to your chosen date library (e.g., dayjs, moment, luxon, or date-fns) and a locale object.

Example using dayjs:

import type { Dayjs } from 'dayjs';
import dayjs from 'dayjs';
import Picker from '@rc-component/picker';
import dayjsGenerateConfig from '@rc-component/picker/generate/dayjs';
import enUS from '@rc-component/picker/locale/en_US';
import '@rc-component/picker/assets/index.css';

export default () => (
  <Picker<Dayjs> generateConfig={dayjsGenerateConfig} locale={enUS} defaultValue={dayjs()} />
);