Basic Usage

Common patterns and examples for using Chronos Picker.

Controlled Component

The most common way to use the picker is as a controlled component, managing the state in your parent component.

Formatted: None

1import { useState } from "react";
2import { DateTimePicker, DateTimeValue } from "@theengineerguy/chronos-picker";
3
4export default function App() {
5  const [value, setValue] = useState<DateTimeValue | null>(null);
6
7  return (
8    <DateTimePicker
9      value={value?.dateTime}
10      onChange={setValue}
11      showTime={false}
12    />
13  );
14}

Timezone Selection

You can preset a timezone or allow the user to select one. When a timezone is set, all dates displayed and selected will be in that timezone.

Selection: None
Zone:

1<DateTimePicker
2  timezone="America/New_York"
3  showTimezoneSelector
4  onChange={(val) => console.log(val.iso)}
5/>

Date-Only Picker

Hide the time picker and only show the calendar. Perfect for birthdays, deadlines, and date selection without time requirements.

Date: None

1<DateTimePicker
2  showTime={false}
3  placeholder="Select date..."
4  onChange={(val) => console.log(val.dateTime.toFormat('yyyy-MM-dd'))}
5/>

Date Range Restrictions

Limit the selectable date range with minDate and maxDate props. Useful for booking systems, event scheduling, and date validation. Only dates within the allowed range can be selected; dates outside are disabled in the calendar.

Custom min date (allowed range start)

Selectable range: 2/16/2026 – 3/18/2026 (30 days from min)

Selected: None

1const [minDate, setMinDate] = useState(new Date());
2const maxDate = new Date(minDate.getTime() + 30 * 24 * 60 * 60 * 1000);
3
4// Optional: let user pick custom min date
5<DateTimePicker value={minDate} onChange={(v) => setMinDate(v.dateTime.toJSDate())} showTime={false} />
6
7{/* Show allowed range so users understand the constraint */}
8<p>Selectable: {minDate.toLocaleDateString()} – {maxDate.toLocaleDateString()}</p>
9
10<DateTimePicker
11  minDate={minDate}
12  maxDate={maxDate}
13  placeholder="Pick a date in range"
14  onChange={setValue}
15  showTime={false}
16/>

Date Range Picker (Start & End)

Use selectionMode="range" to select a start and end date. The calendar shows the selected range with a bar between dates and circles on start/end. A summary header displays the number of nights and the date range (e.g. "3 nights", "11 Feb 2026 – 14 Feb 2026").

Select a start date, then an end date.

1import { DateTimePicker, DateTimeRangeValue } from "@theengineerguy/chronos-picker";
2
3const [range, setRange] = useState<DateTimeRangeValue | null>(null);
4
5<DateTimePicker
6  selectionMode="range"
7  rangeValue={range ? { start: range.start.dateTime, end: range.end.dateTime } : null}
8  onRangeChange={setRange}
9  placeholder="Select check-in and check-out"
10  showTime={false}
11/>
12
13{/* range.start, range.end (DateTimeValue), range.nights */}

12-Hour Format

Display time in 12-hour format with AM/PM. Great for user-facing applications where 12-hour format is preferred.

12-hour format: None

1<DateTimePicker
showTime={true}
use24Hour={false}
onChange={(val) => {
  // Format with AM/PM
  console.log(val.dateTime.toFormat('hh:mm a'));
}}
8/>

Orientation

Control the layout of the calendar and time panel with the orientation prop. Use portrait (default) for a stacked layout, or landscape for calendar and time side-by-side—handy on wider screens.

portrait (default)

landscape

Selected: None (shared between both pickers)

1{/* Stacked: calendar above, time below */}
2<DateTimePicker orientation="portrait" showTime={true} onChange={setValue} />
3
4{/* Side-by-side: calendar left, time right */}
5<DateTimePicker orientation="landscape" showTime={true} onChange={setValue} />

Disabled State

Disable the picker when interaction should be prevented, such as during form submission or when conditions aren't met.

1const [isSubmitting, setIsSubmitting] = useState(false);
2
3<DateTimePicker
4  disabled={isSubmitting}
5  onChange={setValue}
6/>

With Default Value

Set an initial value when the component mounts. Useful for edit forms or when you want to show a pre-selected date.

1import { DateTime } from "luxon";
2import { useState } from "react";
3
4export default function App() {
5  // Initialize with current date/time
6  const [value, setValue] = useState<DateTimeValue>({
7    dateTime: DateTime.now(),
8    formatted: DateTime.now().toFormat('MMM dd, yyyy HH:mm'),
9    iso: DateTime.now().toISO(),
10  });
11
12  return <DateTimePicker value={value.dateTime} onChange={setValue} />;
13}

Form Integration

Integrate with popular form libraries like React Hook Form or Formik. The picker works seamlessly with controlled form state.

1import { useForm, Controller } from "react-hook-form";
2import { DateTimePicker } from "@theengineerguy/chronos-picker";
3
4export default function MyForm() {
const { control, handleSubmit } = useForm();
6
const onSubmit = (data) => {
  console.log("Selected date:", data.appointmentDate?.iso);
};
10
return (
  <form onSubmit={handleSubmit(onSubmit)}>
    <Controller
      name="appointmentDate"
      control={control}
      rules={{ required: "Date is required" }}
      render={({ field }) => (
        <DateTimePicker
          value={field.value?.dateTime}
          onChange={field.onChange}
          placeholder="Select appointment date"
        />
      )}
    />
    <button type="submit">Submit</button>
  </form>
);
28}

Custom Date Format

Format the output using Luxon's powerful formatting options. Access the DateTime object directly for complete control.

1<DateTimePicker
onChange={(val) => {
  // Different format options
  console.log(val.iso);  // ISO 8601: "2024-03-15T14:30:00.000-04:00"
  console.log(val.formatted);  // Default format
6
  // Custom formats using Luxon
  const dt = val.dateTime;
  console.log(dt.toFormat('yyyy-MM-dd'));  // "2024-03-15"
  console.log(dt.toFormat('MMMM dd, yyyy'));  // "March 15, 2024"
  console.log(dt.toFormat('EEE, MMM d'));  // "Fri, Mar 15"
  console.log(dt.toLocaleString());  // Locale-aware format
13
  // For API calls
  console.log(dt.toISO());  // Full ISO string
  console.log(dt.toMillis());  // Unix timestamp (ms)
  console.log(dt.toSeconds());  // Unix timestamp (seconds)
}}
19/>

Working with Timezones

Handle timezone conversions and work with dates across different timezones. Perfect for global applications and scheduling systems.

1import { DateTime } from "luxon";
2
3<DateTimePicker
4  timezone="America/Los_Angeles"
5  showTimezoneSelector
6  onChange={(val) => {
7    const pst = val.dateTime;  // In Pacific time
8
9    // Convert to other timezones
10    const est = pst.setZone('America/New_York');
11    const utc = pst.setZone('UTC');
12    const tokyo = pst.setZone('Asia/Tokyo');
13
14    console.log('PST:', pst.toFormat('HH:mm'));
15    console.log('EST:', est.toFormat('HH:mm'));
16    console.log('UTC:', utc.toFormat('HH:mm'));
17    console.log('Tokyo:', tokyo.toFormat('HH:mm'));
18
19    // Store in database (always use ISO or UTC)
20    saveToDatabase(val.iso);
21  }}
22/>

Holidays & Long Weekends

By default, the picker shows national holidays and long weekend suggestions for the selected timezone. Default timezone is Asia/Kolkata; built-in 2026 India holidays and long weekends are included. Red dots indicate national holidays, green highlights suggest long weekends. Hover over dates to see names.

You can add your own dates with customHolidays, or pass holidays to override the default list entirely. Set showHolidays=false to hide built-in holidays.

Default: Asia/Kolkata with built-in 2026 data

Selected: None · Change timezone to see defaults (India only) or add custom dates below.

1// Default: shows India 2026 national holidays + long weekends when timezone is Asia/Kolkata
2<DateTimePicker
3  timezone="Asia/Kolkata"
4  showTime={false}
5  showTimezoneSelector
6  placeholder="Check 2026 holidays..."
7  onChange={setValue}
8/>

Adding custom holidays

Selected: None · Built-in 2026 + custom dates (e.g. Feb 14, Mar 8).

1import { DateTimePicker, DateTimeValue } from "@theengineerguy/chronos-picker";
2
3// customHolidays are merged with default holidays for the timezone
4<DateTimePicker
5  timezone="Asia/Kolkata"
6  showTime={false}
7  customHolidays={[
8    { date: '2026-02-14', name: 'Company Offsite', type: 'long-weekend' },
9    { date: '2026-03-08', name: 'Team Holiday', type: 'national' },
10  ]}
11  onChange={setValue}
12/>

Using package constants or full override

1import {
2  DateTimePicker,
3  INDIAN_HOLIDAYS_2026,
4  LONG_WEEKENDS_2026,
5  getDefaultHolidaysForTimezone,
6} from "@theengineerguy/chronos-picker";
7
8// Use built-in lists manually (e.g. for a different component)
9const india2026 = [...INDIAN_HOLIDAYS_2026, ...LONG_WEEKENDS_2026];
10
11// Get defaults for current timezone (India 2026 for Asia/Kolkata, else [])
12const defaults = getDefaultHolidaysForTimezone("Asia/Kolkata");
13
14// Full override: only show your own list (no built-in)
15<DateTimePicker
16  timezone="Asia/Kolkata"
17  showTime={false}
18  holidays={[
19    { date: '2026-01-01', name: 'New Year', type: 'national' },
20    { date: '2026-12-31', name: 'New Year Eve', type: 'long-weekend' },
21  ]}
22  onChange={setValue}
23/>
24
25// Hide built-in holidays, only show custom
26<DateTimePicker showHolidays={false} customHolidays={myList} onChange={setValue} />