0.1.0

expo-skia-date-wheel-picker

Responsive date and time wheel picker for Expo and React Native, with Skia-rendered overlays and immediate onDateChange updates while the wheel moves.

This package keeps the API small and predictable:

• controlled with a single date: Date value
• supports both date and time modes
• clamps invalid values with minimumDate / maximumDate
• snaps minutes with minuteInterval
• adapts to locale and 12/24-hour rules
• supports timezone-offset editing
• exposes live wheel state through callbacks

Preview

Why this picker

expo-skia-date-wheel-picker is built for cases where a wheel picker should feel responsive and easy to style without introducing a large API surface.

• Immediate updates while scrolling — onDateChange fires as the centered row changes, not only after the wheel becomes idle.
• Skia-enhanced visuals — Skia draws the fade overlays and center guide lines, which keeps the wheel presentation polished and customizable.
• Native snapped wheel interaction — each column uses snapped scrolling with row-based selection.
• Simple controlled model — no separate value / defaultValue split; the picker is driven by date and onDateChange.

Note: Skia is used for the wheel overlay and guide rendering. The selectable rows themselves are rendered with React Native views and text.

Features

• Date mode: year / month / day
• Time mode: hour / minute, plus AM/PM when 12-hour time is active
• Live onDateChange callback during interaction
• onStateChange callback with 'spinning' | 'idle'
• minimumDate / maximumDate clamping
• minuteInterval support for stepped time selection
• Locale-aware labels and 12/24-hour behavior
• timeZoneOffsetInMinutes for editing in another timezone
• Styling props for colors, typography, row height, and visible rows

Installation

Install the published package and required peer dependencies:

npm install @0610studio/expo-skia-date-wheel-picker
npx expo install @shopify/react-native-skia expo-haptics

If you are not using Expo CLI for dependency resolution, make sure @shopify/react-native-skia matches your Expo SDK or React Native setup.

Basic usage

import { useState } from 'react';
import DateWheelPicker from '@0610studio/expo-skia-date-wheel-picker';

export default function Example() {
  const [date, setDate] = useState(new Date('2026-04-22T13:30:00'));

  return (
    <DateWheelPicker
      date={date}
      mode="date"
      onDateChange={setDate}
    />
  );
}

You can also import the named export:

import { DateWheelPicker } from '@0610studio/expo-skia-date-wheel-picker';

The package root also exports its public types, including DatePickerProps, PickerMode, DatePartKey, TimePartKey, PickerOption, PickerColumn, WheelColumnProps, and HexColor.

Common recipes

Time picker with stepped minutes

import { useState } from 'react';
import DateWheelPicker from '@0610studio/expo-skia-date-wheel-picker';

export default function TimeExample() {
  const [date, setDate] = useState(new Date('2026-04-22T13:37:00'));

  return (
    <DateWheelPicker
      date={date}
      mode="time"
      minuteInterval={5}
      onDateChange={setDate}
    />
  );
}

Bounded date selection

import { useState } from 'react';
import DateWheelPicker from '@0610studio/expo-skia-date-wheel-picker';

const minimumDate = new Date('2026-04-10T00:00:00');
const maximumDate = new Date('2026-05-05T23:59:00');

export default function RangeExample() {
  const [date, setDate] = useState(new Date('2026-04-22T13:30:00'));

  return (
    <DateWheelPicker
      date={date}
      mode="date"
      minimumDate={minimumDate}
      maximumDate={maximumDate}
      onDateChange={setDate}
    />
  );
}

Locale and timezone configuration

import { useState } from 'react';
import DateWheelPicker from '@0610studio/expo-skia-date-wheel-picker';

export default function LocaleExample() {
  const [date, setDate] = useState(new Date('2026-04-22T13:30:00Z'));

  return (
    <DateWheelPicker
      date={date}
      mode="time"
      locale="ko-KR"
      timeZoneOffsetInMinutes={540}
      onDateChange={setDate}
    />
  );
}

Live callback handling

import { useState } from 'react';
import DateWheelPicker from '@0610studio/expo-skia-date-wheel-picker';

export default function CallbackExample() {
  const [date, setDate] = useState(new Date('2026-04-22T13:30:00'));
  const [state, setState] = useState<'spinning' | 'idle'>('idle');

  return (
    <DateWheelPicker
      date={date}
      mode="time"
      minuteInterval={10}
      onDateChange={setDate}
      onStateChange={setState}
    />
  );
}

Props

Behavioral notes

• The picker is controlled. Pass a date and update it from onDateChange.
• onDateChange is designed for live synchronization, so form state can update immediately while the wheel moves.
• minimumDate and maximumDate clamp both the incoming value and the available wheel options.
• minuteInterval rounds to the nearest valid minute step.
• In time mode, the period column only appears when the current hour-cycle configuration uses 12-hour time.
• timeZoneOffsetInMinutes changes the editable clock representation without changing the overall API shape.
• visibleRows is normalized so the active row stays centered.
• rowHeight <= 0 falls back to the internal default.

Example app

This repository includes an Expo example app in example/. It uses expo-router, so each scenario has its own route.

The example app intentionally aliases the local source as expo-skia-date-wheel-picker for repo development. When you install from npm in a real app, import from @0610studio/expo-skia-date-wheel-picker as shown above.

Included example pages

• / — overview and route index
• /date — minimal controlled date mode
• /time — time mode with minuteInterval
• /limits — minimumDate / maximumDate
• /locale-timezone — locale-aware formatting and timezone offset handling
• /styling — colors, row height, visible rows, and typography
• /callbacks — live onDateChange updates and onStateChange

Run the example app

cd example
npm install
npm run start

License

MIT