Skip to Content
DateInput

DateInput

Input field with calendar that lets user enter dates.

Source

#

Documentation

#

Usage

"use client";
 
import type { ComponentPropsWithoutRef } from "react";
 
import { DateInput, Field } from "@optiaxiom/react";
 
export function App({
  description,
  error,
  label = "Input label",
  required = false,
}: Pick<
  ComponentPropsWithoutRef<typeof Field>,
  "description" | "error" | "label" | "required"
>) {
  return (
    <Field
      description={description}
      error={error}
      label={label}
      required={required}
      w="224"
    >
      <DateInput />
    </Field>
  );
}

#

Controlled

Use the value and defaultValue props to toggle between controlled and uncontrolled usage. And combine it with onValueChange / onChange to listen for changes to the state.

Input value: 

"use client";
 
import { DateInput, Group, Text } from "@optiaxiom/react";
import { useState } from "react";
 
export function App() {
  const [value, setValue] = useState("");
 
  return (
    <Group flexDirection="column" gap="16" w="224">
      <DateInput onValueChange={setValue} value={value} />
      <Text fontSize="md">Input value: {value}</Text>
    </Group>
  );
}

#

Value formats

The value prop accepts date strings in specific formats. For type="date", use YYYY-MM-DD format. For type="datetime-local", use YYYY-MM-DDTHH:MM format.

Date format: 2025-01-22

DateTime format: 2025-01-22T14:30

"use client";
 
import { DateInput, Group, Text } from "@optiaxiom/react";
import { useState } from "react";
 
export function App() {
  const [dateValue, setDateValue] = useState("2025-01-22");
  const [datetimeValue, setDatetimeValue] = useState("2025-01-22T14:30");
 
  return (
    <Group flexDirection="column" gap="16">
      <Group flexDirection="column" gap="16">
        <DateInput onValueChange={setDateValue} type="date" value={dateValue} />
        <Text color="fg.secondary" fontSize="sm">
          Date format:{" "}
          <Text asChild fontWeight="600">
            <span>{dateValue || "YYYY-MM-DD"}</span>
          </Text>
        </Text>
      </Group>
      <Group flexDirection="column" gap="16">
        <DateInput
          onValueChange={setDatetimeValue}
          type="datetime-local"
          value={datetimeValue}
        />
        <Text color="fg.secondary" fontSize="sm">
          DateTime format:{" "}
          <Text asChild fontWeight="600">
            <span>{datetimeValue || "YYYY-MM-DDTHH:MM"}</span>
          </Text>
        </Text>
      </Group>
    </Group>
  );
}

#

Placeholder

Use the placeholder prop to specify a placeholder date or time. The value format must be an Instant, PlainDate, PlainDateTime, or PlainTime.

import { DateInput, Field, Group } from "@optiaxiom/react";
 
export function App() {
  return (
    <Group flexDirection="column" gap="16">
      <Field label="Default time at 2:30 PM">
        <DateInput placeholder="14:30" type="datetime-local" />
      </Field>
      <Field label="Default calendar to January 2025">
        <DateInput placeholder="2025-01-01" type="date" />
      </Field>
    </Group>
  );
}

#

Error state

Enable the error prop to display the error state of the input field.

"use client";
 
import type { ComponentPropsWithoutRef } from "react";
 
import { DateInput } from "@optiaxiom/react";
 
export function App({
  error = true,
}: Pick<ComponentPropsWithoutRef<typeof DateInput>, "error">) {
  return <DateInput error={error} />;
}

#

Disabled state

Enable the disabled prop to toggle the disabled state of the input field.

"use client";
 
import type { ComponentPropsWithoutRef } from "react";
 
import { DateInput } from "@optiaxiom/react";
 
export function App({
  disabled = true,
}: Pick<ComponentPropsWithoutRef<typeof DateInput>, "disabled">) {
  return <DateInput disabled={disabled} />;
}

#

Required

By default we show a clear button when there is value but this can be removed by toggling the required prop.

"use client";
 
import { DateInput, Field } from "@optiaxiom/react";
 
export function App() {
  return (
    <Field label="Start date" required w="224">
      <DateInput required />
    </Field>
  );
}

#

Sizes

Use the size prop to control the size of the input.

import { DateInput, Group } from "@optiaxiom/react";
 
export function App() {
  return (
    <Group flexDirection="column" gap="16">
      <DateInput placeholder="Medium (default)" size="md" />
      <DateInput placeholder="Large" size="lg" />
    </Group>
  );
}

#

Addons

Use the addonAfter prop to display content inside the input at the end.

UTC
import { DateInput, Field } from "@optiaxiom/react";
 
export function App() {
  return (
    <Field label="Select date">
      <DateInput addonAfter="UTC" />
    </Field>
  );
}

#

Max

Use the max prop to specify the latest date the user can enter. Will disable all dates after the specified date. Pass it in the same format as value: with type="datetime-local" it must include a time, e.g. 2030-12-31T23:59.

"use client";
 
import { DateInput } from "@optiaxiom/react";
 
export function App() {
  return <DateInput defaultValue="2025-05-15" max="2025-05-20" />;
}

#

Min

Use the min prop to specify the earliest date the user can enter. Will disable all dates prior to the specified date. Pass it in the same format as value: with type="datetime-local" it must include a time, e.g. 2025-01-01T00:00.

"use client";
 
import { DateInput } from "@optiaxiom/react";
 
export function App() {
  return <DateInput defaultValue="2025-05-15" min="2025-05-10" />;
}

#

Date and time

Use the type prop to switch between date and datetime-local inputs.

"use client";
 
import type { ComponentPropsWithoutRef } from "react";
 
import { DateInput } from "@optiaxiom/react";
 
export function App({
  type = "datetime-local",
}: Pick<ComponentPropsWithoutRef<typeof DateInput>, "type">) {
  return <DateInput type={type} />;
}

#

Localization

The calendar popover is localized to the browser locale (via navigator.language) by default, which controls the captions, weekday headers, week start, and AM/PM labels. Override the locale for the whole app by passing the locale prop to AxiomProvider.

#

Weekend

Use the weekend prop to provide one or more matchers to denote weekends on the calendar.

"use client";
 
import { DateInput } from "@optiaxiom/react";
 
export function App() {
  return <DateInput weekend={{ dayOfWeek: [0, 6] }} />;
}

#

Holiday

Use the holiday prop to provide one or more matchers to denote holidays on the calendar.

"use client";
 
import { DateInput } from "@optiaxiom/react";
 
export function App() {
  return <DateInput holiday={(day) => day.getDate() === 5} />;
}

#

Date matchers

The holiday and weekend props support various matcher types including specific dates, date ranges, date intervals, day of week, and custom functions. You can also combine multiple matchers.

import { DateInput, Field, Group } from "@optiaxiom/react";
 
export function App() {
  const publicHolidays = [
    new Date(2025, 0, 1), // New Year's Day
    new Date(2025, 6, 4), // Independence Day
    new Date(2025, 11, 25), // Christmas
  ];
 
  return (
    <Group flexDirection="column" gap="16">
      <Field label="Specific dates as holidays">
        <DateInput holiday={publicHolidays} />
      </Field>
      <Field label="Date range as holidays">
        <DateInput
          holiday={{ from: new Date(2025, 11, 24), to: new Date(2025, 11, 31) }}
        />
      </Field>
      <Field label="Multiple matchers (weekends + date range)">
        <DateInput
          holiday={[
            { dayOfWeek: [0, 6] },
            { from: new Date(2025, 11, 24), to: new Date(2025, 11, 31) },
          ]}
        />
      </Field>
    </Group>
  );
}

#

Related

Field

Wrapper for inputs to provide context such as label, help text and required state.

Input

Basic text field for capturing user input.

DateRangePicker

Calendar popover that lets user pick date ranges.

#

Props

#

DateInput

import { DateInput } from "@optiaxiom/react";
// or
import { DateInput } from "@optiaxiom/react/date-input";

Supports all Box props in addition to its own. Renders a <div> element.

Prop

addonAfter

Display content inside the input at the end.

ReactNode

addonBefore

Display content inside the input at the start.

ReactNode

addonPointerEvents

When this prop is set to none clicking empty space inside the addon will focus the input box.

"none" | "auto"

appearance

Control the appearance of the input.

"number" | "default"

asChild

Change the default rendered element for the one passed as a child, merging their props and behavior.

Read the Composition guide for more details.

false | true

autoFocus

Whether the input should be focused on mount.

false | true

children

ReactNode

className

string

defaultValue

The initial value of the input, when uncontrolled.

string | number | readonly string[]

disabled

Whether the input is disabled.

false | true

error

Whether to show the input error state. Automatically set when used inside a Field component with an error prop.

false | true

holiday

Apply the holiday modifier to the matching days.

false | true | (date: Date) => boolean | Date | Date[] | DateRange | DateBefore | DateAfter | DateInterval | DayOfWeek | Matcher[]

htmlSize

Control the native input size attribute.

number

max

The latest date the user can enter, in the same format as value: YYYY-MM-DD for type="date", and YYYY-MM-DDTHH:MM for type="datetime-local" (e.g. “2030-12-31T23:59”). The browser ignores a value in the wrong format.

string | number

maxLength

The maximum number of characters allowed in a text input or textarea. Wrap it in a Field with showCount to show the character count.

number

min

The earliest date the user can enter, in the same format as value: YYYY-MM-DD for type="date", and YYYY-MM-DDTHH:MM for type="datetime-local" (e.g. “2025-01-01T00:00”). The browser ignores a value in the wrong format.

string | number

name

The name of the form control element.

string

onValueChange

Handler that is called when the value changes.

(value: string) => void

placeholder

The placeholder date and time to use when no value has yet been selected.

The value format must an Instant, PlainDate, PlainDateTime, or PlainTime. The default date and time to use in the calendar picker when no value has been selected.

NOTE: This is NOT a placeholder hint text for the input field. Native date inputs do not support placeholder text. The value format must be an Instant, PlainDate, PlainDateTime, or PlainTime (e.g., “2024-01-01”, “2024-01-01T12:00”, “12:00”).

// Set default time to noon when picking dates
<DateInput placeholder="12:00" />

// Set default date to a specific date
<DateInput placeholder="2024-01-01" />

string

required

Whether selecting this input is required.

false | true

size

Control the size of the input.

"md" | "lg" | "xl"

type

Control whether the input allows only date or both date and time.

"date" | "datetime-local"

Default: date

value

The value of the input. Use with onValueChange to control it.

string | number | readonly string[]

weekend

Apply the weekend modifier to the matching days.

false | true | (date: Date) => boolean | Date | Date[] | DateRange | DateBefore | DateAfter | DateInterval | DayOfWeek | Matcher[]

#

Accessibility

#

Keyboard interactions

Key

Description

Space

When focus is on DateInput, opens the calendar and focuses the selected day (or today’s date). When focus is on a day, selects the focused day.

Enter

Selects the focused day in the calendar.

ArrowUpArrowDownArrowRightArrowLeft

Navigate between days in the calendar.

PageUpPageDown

Navigate between months in the calendar.

ShiftPageUpShiftPageDown

Navigate between years in the calendar.

Esc

Closes the calendar popover and moves focus back to DateInput.

#

Changelog

#

3.1.0

#

1.4.0

  • Moved component out of Alpha.

    // Before
import { DateInput } from "@optiaxiom/react/unstable";
 
// After
import { DateInput } from "@optiaxiom/react";

#

0.12.1

  • Added component
Last updated on
DataTableDateRangePicker