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/11/2026 – 3/13/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
  
  // 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
  
  // 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
timezone="America/Los_Angeles"
showTimezoneSelector
onChange={(val) => {
  const pst = val.dateTime;  // In Pacific time
  
  // Convert to other timezones
  const est = pst.setZone('America/New_York');
  const utc = pst.setZone('UTC');
  const tokyo = pst.setZone('Asia/Tokyo');
  
  console.log('PST:', pst.toFormat('HH:mm'));
  console.log('EST:', est.toFormat('HH:mm'));
  console.log('UTC:', utc.toFormat('HH:mm'));
  console.log('Tokyo:', tokyo.toFormat('HH:mm'));
  
  // Store in database (always use ISO or UTC)
  saveToDatabase(val.iso);
}}
22/>