react-component/picker

README

@rc-component/picker

_{Part of the Ant Design ecosystem.}

📅 React date, time, range, and panel picker primitives with pluggable date-library generate configs.

Highlights

Single picker, range picker, and panel-only picker exports.
Date, time, week, month, quarter, and year modes.
Pluggable generateConfig adapters for date-fns, dayjs, luxon, and moment.
Locale packages exposed from @rc-component/picker/locale/*.
Controlled value, popup state, panel value, presets, disabled dates, semantic class names, and custom cell rendering.
TypeScript definitions for picker props, range values, locale, date-library adapters, and refs.
Used by Ant Design as the shared date and time picker foundation.

Install

npm install @rc-component/picker

Install the date library you plan to use if it is not already in your project:

npm install dayjs

Usage

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()} />
);

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()],
      },
    ]}
  />
);

Examples

Run the local dumi site:

npm install
npm start

Then open http://localhost:8000.

API

Exports

Export	Description
`Picker`	Input picker for one date/time value or multiple values.
`RangePicker`	Input picker for start and end date/time values.
`PickerPanel`	Panel-only picker without the input trigger.
`generate/*`	Date-library adapters for date-fns, dayjs, luxon, and moment.
`locale/*`	Locale objects for picker UI text and formats.
`interface`	Shared TypeScript types.

Shared Picker Props

Property	Type	Default	Description
allowClear	`boolean \| AllowClearConfig`	`true`	Show the clear button or customize it.
cellRender	`CellRender<DateType>`	-	Customize date, time, and range cells.
changeOnBlur	`boolean`	-	Commit typed values on blur when valid.
className	`string`	-	Class name for the picker root.
classNames	`SemanticClassNames`	-	Semantic class names for root and popup slots.
components	`Components<DateType>`	-	Component overrides.
defaultOpen	`boolean`	-	Initial popup open state.
disabledDate	`DisabledDate<DateType>`	-	Disable selectable dates.
format	`string \| string[] \| FormatType<DateType>[]`	locale dependent	Format and parse input values.
generateConfig	`GenerateConfig<DateType>`	required	Date-library adapter.
getPopupContainer	`(node: HTMLElement) => HTMLElement`	-	Popup container.
inputReadOnly	`boolean`	-	Make input read-only.
locale	`Locale`	required	Locale text and formats.
maxDate	`DateType`	-	Latest selectable date.
minDate	`DateType`	-	Earliest selectable date.
needConfirm	`boolean`	-	Require OK confirmation before change.
open	`boolean`	-	Controlled popup open state.
picker	`'time' \| 'date' \| 'week' \| 'month' \| 'quarter' \| 'year'`	`date`	Picker mode.
pickerValue	`DateType \| [DateType, DateType] \| null`	-	Controlled panel date.
placeholder	`string \| [string, string]`	-	Input placeholder.
popupClassName	`string`	-	Class name for popup.
presets	`ValueDate<DateType>[]`	-	Preset values.
previewValue	`false \| 'hover'`	`hover`	Preview hovered values in input.
showNow	`boolean`	-	Show the "now" button.
showTime	`boolean \| SharedTimeProps`	`false`	Enable time selection.
showToday	`boolean`	-	Show the "today" button.
styles	`SemanticStyles`	-	Semantic styles for root and popup slots.
suffix	`ReactNode`	-	Custom suffix.
onOpenChange	`(open: boolean) => void`	-	Triggered when popup open state changes.
onPanelChange	`(value, mode) => void`	-	Triggered when panel mode changes.

Picker Props

Property	Type	Default	Description
defaultPickerValue	`DateType \| null`	-	Initial panel date whenever the popup opens.
defaultValue	`DateType \| DateType[]`	-	Initial selected value.
multiple	`boolean`	`false`	Enable multiple selection for supported modes.
tagRender	`(props: CustomTagProps<DateType>) => ReactNode`	-	Customize multiple value tags.
value	`DateType \| DateType[] \| null`	-	Controlled selected value.
onCalendarChange	`(date, dateString, info) => void`	-	Triggered while calendar selection changes.
onChange	`(date, dateString) => void`	-	Triggered when selected value changes.
onOk	`(value) => void`	-	Triggered when OK is clicked.

RangePicker Props

Property	Type	Default	Description
allowEmpty	`boolean \| [boolean, boolean]`	`false`	Allow empty start or end values.
defaultPickerValue	`[DateType, DateType] \| DateType \| null`	-	Initial panel date whenever the popup opens.
defaultValue	`[DateType \| null \| undefined, DateType \| null \| undefined]`	-	Initial selected range.
disabled	`boolean \| [boolean, boolean]`	`false`	Disable the whole range or one side.
order	`boolean`	`true`	Keep selected range ordered.
ranges	`Record<string, RangeValue \| () => RangeValue>`	-	Deprecated preset API. Use `presets`.
separator	`ReactNode`	-	Separator between range inputs.
value	`[DateType \| null \| undefined, DateType \| null \| undefined] \| null`	-	Controlled selected range.
onCalendarChange	`(dates, dateStrings, info) => void`	-	Triggered while range selection changes.
onChange	`(dates, dateStrings) => void`	-	Triggered when selected range changes.
onOk	`(values) => void`	-	Triggered when OK is clicked.

Time Options

Property	Type	Default	Description
changeOnScroll	`boolean`	`false`	Change time values on scroll.
defaultOpenValue	`DateType \| DateType[]`	-	Default time template when selection is empty.
disabledTime	`(date, range?, info?) => DisabledTimes`	-	Disable hours, minutes, seconds, or milliseconds.
format	`string`	-	Time format.
hideDisabledOptions	`boolean`	`false`	Hide disabled time options.
hourStep	`number`	`1`	Hour interval.
millisecondStep	`number`	`1`	Millisecond interval.
minuteStep	`number`	`1`	Minute interval.
secondStep	`number`	`1`	Second interval.
showHour	`boolean`	`true`	Show hour column.
showMillisecond	`boolean`	`false`	Show millisecond column.
showMinute	`boolean`	`true`	Show minute column.
showNow	`boolean`	-	Show now shortcut.
showSecond	`boolean`	`true`	Show second column.
use12Hours	`boolean`	`false`	Use 12-hour display.

Development

npm install
npm start
npm test
npm run tsc
npm run coverage
npm run compile
npm run build

The dumi site runs at http://localhost:8000 by default.

Release

npm run prepublishOnly

The release flow is handled by @rc-component/np through the rc-np command after the package build.

License

@rc-component/picker is released under the MIT license.

Clear configuration

allowClear accepts a boolean or an AllowClearConfig object from @rc-component/util:

interface AllowClearConfig {
  clearIcon?: React.ReactNode;
  disabled?: boolean;
  tabIndex?: number;
  label?: string;
}

All fields are optional. disabled: true behaves like allowClear={false}: the clear button and space reserved solely for it are removed; the input remains editable. Existing suffixes and other content are preserved. This changes the previous hidden-button spacing behavior where applicable.

tabIndex affects only the clear button; -1 removes it from Tab navigation while retaining mouse activation. label supplies its accessible name through aria-label. Defaults, clear values, callbacks, and component state restrictions are unchanged.