@elberpg/ex-date-picker

Composable date and time pickers for React Native / Expo.
Drum-scroll columns — no native dependencies, no @elberpg/ex-modal required.

Spanish docs: README_ES.md

---

Preview

Default — Date	Default — Time

Fully themeable via global style objects — no props required.

Dark ☕ — Date	Dark ☕ — Time	Square ⬛ — Date	Square ⬛ — Time

---

Installation

npm install @elberpg/ex-date-picker

---

Concept — composable pattern

Each picker and modal are independent components. You compose them:

<DatePickerModal visible={open} onClose={onClose} onConfirm={() => onConfirm(draft)}>
  <DatePicker value={draft} onChange={setDraft} />
</DatePickerModal>

This gives full style control over each part independently.

---

DatePicker

Scroll columns for day, month, and year. Use standalone or inside any modal.

import { DatePicker } from '@elberpg/ex-date-picker';

<DatePicker
  value={date}
  onChange={setDate}
  locale="en-US"
/>

Props

Prop	Type	Default	Description
value	Date | DatePickerValue	today	Current value
onChange	(date: Date) => void	—	Called on every scroll change
locale	string	'en'	Locale for month names
minYear	number	current − 100	Minimum year
maxYear	number	current + 10	Maximum year
itemHeight	number	from theme	Row height in px
selectedColor	string	from theme	Color of the selected item
unselectedColor	string	from theme	Color of unselected items
style	ViewStyle	—	Container style

---

TimePicker

Scroll columns for hour and minute. Supports 12-hour (AM/PM) mode.

import { TimePicker } from '@elberpg/ex-date-picker';

<TimePicker
  value={time}
  onChange={setTime}
  use12h={false}
/>

Props

Prop	Type	Default	Description
value	TimeValue | Date	now	Current value
onChange	(time: TimeValue) => void	—	Called on every scroll change
use12h	boolean	false	12-hour mode with AM/PM column
itemHeight	number	from theme	Row height in px
selectedColor	string	from theme	Color of the selected item
unselectedColor	string	from theme	Color of unselected items
style	ViewStyle	—	Container style

TimeValue

interface TimeValue {
  hours: number;    // 0–23 (or 1–12 in 12h mode)
  minutes: number;  // 0–59
}

---

DatePickerModal — native RN Modal

Bottom-sheet using React Native's Modal component. Renders on top of everything including toasts.

import { DatePicker, DatePickerModal } from '@elberpg/ex-date-picker';

const [open, setOpen]   = useState(false);
const [date, setDate]   = useState(new Date());
const [draft, setDraft] = useState(new Date());

// Open: sync draft with current value
<Pressable onPress={() => { setDraft(date); setOpen(true); }}>
  <Text>{date.toLocaleDateString()}</Text>
</Pressable>

<DatePickerModal
  visible={open}
  onClose={() => setOpen(false)}
  onConfirm={() => { setDate(draft); setOpen(false); }}
  title="Select date"
>
  <DatePicker value={draft} onChange={setDraft} locale="en-US" />
</DatePickerModal>

---

DatePickerModalOverlay — style-based overlay

Same API as DatePickerModal but uses position: absolute instead of RN's Modal.
Avoids conflicts with toasts, sheets, and other overlays. Must be placed at root level.

import { DatePicker, DatePickerModalOverlay } from '@elberpg/ex-date-picker';

<DatePickerModalOverlay
  visible={open}
  onClose={() => setOpen(false)}
  onConfirm={() => { setDate(draft); setOpen(false); }}
  title="Select date"
>
  <DatePicker value={draft} onChange={setDraft} />
</DatePickerModalOverlay>

---

TimePickerModal / TimePickerModalOverlay

Same API as the date variants. Just swap DatePicker for TimePicker as children.

import { TimePicker, TimePickerModal } from '@elberpg/ex-date-picker';

<TimePickerModal
  visible={open}
  onClose={() => setOpen(false)}
  onConfirm={() => { setTime(draft); setOpen(false); }}
  title="Select time"
  clearable
  onClear={() => { setTime(undefined); setOpen(false); }}
>
  <TimePicker value={draft} onChange={setDraft} use12h />
</TimePickerModal>

---

Modal props — PickerModalProps

Shared by DatePickerModal, DatePickerModalOverlay, TimePickerModal, TimePickerModalOverlay.

Prop	Type	Default	Description
visible	boolean	—	Shows or hides the modal
onClose	() => void	—	Called when the backdrop or Cancel is tapped
onConfirm	() => void	—	Called when Confirm is tapped
children	ReactNode	—	The picker to render inside
title	string	—	Modal title
confirmLabel	string	'Confirm'	Confirm button text
cancelLabel	string	'Cancel'	Cancel button text
clearable	boolean	false	Show a Clear button
clearLabel	string	'Clear'	Clear button text
onClear	() => void	—	Called when Clear is tapped
btnConfirm	({ onPress }) => ReactNode	—	Replace the Confirm button
btnCancel	({ onPress }) => ReactNode	—	Replace the Cancel button
btnClear	({ onPress }) => ReactNode	—	Replace the Clear button

---

Global styles

There are two separate style objects — one for the picker, one for the modal shell.

ExDatePicker.styles — picker (scroll columns)

import { ExDatePicker } from '@elberpg/ex-date-picker';

ExDatePicker.styles.selectedColor   = '#0a84ff';
ExDatePicker.styles.unselectedColor = '#8e8e93';
ExDatePicker.styles.itemHeight      = 52;
ExDatePicker.styles.fontFamily      = 'Georgia';
ExDatePicker.styles.lineColor       = '#3a3a3c';
ExDatePicker.styles.columnLabel     = { fontSize: 11, color: '#888', textTransform: 'uppercase' };

Field	Type	Description
selectedColor	string	Color of the selected scroll item
unselectedColor	string	Color of unselected scroll items
itemHeight	number	Height of each scroll row in px
fontFamily	string	Font family for scroll item text
lineColor	string	Color of the two selection indicator lines
columnLabel	TextStyle	Column labels (DAY · MONTH · YEAR / HOUR · MIN)

ExDatePickerModal.styles — modal shell

import { ExDatePickerModal } from '@elberpg/ex-date-picker';

ExDatePickerModal.styles.card = {
  backgroundColor: '#1c1c1e',
  borderTopLeftRadius: 28,
  borderTopRightRadius: 28,
};
ExDatePickerModal.styles.title          = { fontSize: 17, fontWeight: '700', color: '#fff' };
ExDatePickerModal.styles.btnConfirm     = { backgroundColor: '#0a84ff' };
ExDatePickerModal.styles.btnConfirmText = { fontSize: 15, fontWeight: '600', color: '#fff' };
ExDatePickerModal.styles.backdropColor  = 'rgba(0,0,0,0.65)';

Field	Type	Description
card	ViewStyle	Main card (background, border radius, padding)
pill	ViewStyle	Drag pill at the top
title	TextStyle	Modal title (fontSize, color, fontFamily…)
headerBorder	ViewStyle	Separator below the title
btnConfirm	ViewStyle	Confirm button container
btnCancel	ViewStyle	Cancel button container
btnClear	ViewStyle	Clear button container
btnConfirmText	TextStyle	Confirm button text
btnCancelText	TextStyle	Cancel button text
btnClearText	TextStyle	Clear button text
backdropColor	string	Backdrop color + opacity (rgba(…))

---

Custom button example

<DatePickerModal
  btnConfirm={({ onPress }) => (
    <Pressable onPress={onPress} style={{ backgroundColor: '#0a84ff', borderRadius: 12, flex: 1, height: 48, alignItems: 'center', justifyContent: 'center' }}>
      <Text style={{ color: '#fff', fontWeight: '700' }}>Done</Text>
    </Pressable>
  )}
>
  <DatePicker value={draft} onChange={setDraft} />
</DatePickerModal>

---

Important rule

Place modals outside any ScrollView.

// ✅ Correct
return (
  <>
    <SafeAreaView>
      <ScrollView>...</ScrollView>
    </SafeAreaView>
    <DatePickerModal visible={open} onClose={onClose} onConfirm={onConfirm}>
      <DatePicker value={draft} onChange={setDraft} />
    </DatePickerModal>
  </>
);

// ❌ Wrong — the modal scrolls with the content
return (
  <ScrollView>
    <DatePickerModal visible={open} .../>
  </ScrollView>
);