# Date Input

A date field typed one part at a time, like a native date input.

Source: [date-input.tsx](https://github.com/jakejarvis/jarvis-ui/blob/main/src/components/ui/date-input.tsx)

```tsx
import { DateInput } from "@/components/ui/date-input";

export default function DateInputBasic() {
  return <DateInput aria-label="Due date" />;
}
```

## Installation

Add the registry, once per project:

```bash
npx shadcn@latest registry add @jarvis=https://ui.jarv.is/r/{name}.json
```

Then add the component:

```bash
npx shadcn@latest add @jarvis/date-input
```

## Usage

```tsx
"use client";

import * as React from "react";

import { DateInput } from "@/components/ui/date-input";

export function DueDateInput() {
  const [date, setDate] = React.useState<Date | null>(null);

  return <DateInput aria-label="Due date" value={date} onValueChange={setDate} />;
}
```

`DateInput` splits the date into month, day and year parts, in the order its locale uses. Each part
takes typed digits and moves on to the next part once it's full, so typing `6`, `1`, `2`, `2025`
gives 06/12/2025. Typing a `/`, `-`, `.` or space moves on early. A part also moves on as soon as no
other digit could follow, so a `4` in the day, or a `3` in the day of February, fills it at once.

Typing letters in any part sets the month: `j` gives January, `ju` June and `jul` July. Typing `j`
again cycles through the months that start with it. A two-digit year becomes the nearest year that
ends in those digits, so `98` is 1998 and `31` is 2031. If someone leaves the field with a month and
a day but no year, the input fills in the current year.

The up and down arrow keys step a part's value, starting from today's date when the part is empty.
Page Up and Page Down step the day by a week, the month by 3 and the year by 10. Backspace clears a
part. Pasting a date such as `2025-06-12`, `6/12/2025`, `June 12, 2025` or `12 Jun 2025` fills every
part. The day and month are read in the locale's order, unless only the other order gives a real
date. Pasting a number fills only the focused part.

The value is a `Date` at midnight. `onValueChange` receives it once every part is filled in. It
receives `null` once a part is cleared, or when the date doesn't exist, such as February 30, which
also makes the input invalid. To let users pick from a calendar too, use a
[Date Picker](https://ui.jarv.is/components/date-picker.md), which is built on Date Input.

## Examples

### With a label

Put the input in a [Field](https://ui.jarv.is/components/field.md) with a `FieldLabel`. Screen readers announce the
field's `FieldDescription` and `FieldError` with the input, and the input becomes invalid or
disabled along with the field. Without a visible label, give the input an `aria-label`.

```tsx
import { DateInput } from "@/components/ui/date-input";
import { Field, FieldDescription, FieldLabel } from "@/components/ui/field";

export default function DateInputWithLabel() {
  return (
    <Field className="w-48">
      <FieldLabel>Birthday</FieldLabel>
      <DateInput defaultValue={new Date(1990, 3, 18)} className="w-full" />
      <FieldDescription>We'll send you something on the day.</FieldDescription>
    </Field>
  );
}
```

### Range

With `mode="range"`, the input holds a start date and an end date, and the value is a `{ from, to }`
range once both are filled in. An end date before the start date makes the input invalid. Pasting a
range such as `6/26/2025 – 7/4/2025`, `2025-06-26/2025-07-04` or `Mar 5 – 10, 2024` fills both ends.
An end written without its year or month takes them from the other end. When a pasted range crosses
into a new year, one end moves across the year boundary: `Dec 28 – Jan 3` ends in January of the
next year, or starts in December of the previous year when that's nearer to today.

```tsx
import { DateInput } from "@/components/ui/date-input";

export default function DateInputRange() {
  return (
    <DateInput
      mode="range"
      defaultValue={{ from: new Date(2025, 5, 26), to: new Date(2025, 6, 4) }}
      aria-label="Trip dates"
    />
  );
}
```

### Locale

The input formats the date with the order and separators of its `locale`, a BCP 47 tag such as
`"de-DE"`, as [Calendar](https://ui.jarv.is/components/calendar.md)'s is. It also accepts month names in that language, so
pasting `3. Oktober 2025` fills it too. `labels` replaces the input's own text, its parts'
accessible names and its validation messages, so they match the locale. Pass only the ones you want
to change.

```tsx
"use client";

import { DateInput } from "@/components/ui/date-input";

export default function DateInputLocale() {
  return (
    <DateInput
      locale="de-DE"
      defaultValue={new Date(2025, 9, 3)}
      aria-label="Datum"
      labels={{
        year: "Jahr",
        month: "Monat",
        day: "Tag",
        empty: "Leer",
        incomplete: "Gib ein vollständiges Datum ein.",
        nonexistent: (month, days) => `Der ${month} hat ${days} Tage.`,
      }}
    />
  );
}
```

### Earliest and latest dates

The input becomes invalid for a date before `min` or after `max`.

```tsx
import { DateInput } from "@/components/ui/date-input";
import { Field, FieldDescription, FieldLabel } from "@/components/ui/field";

export default function DateInputMinMax() {
  return (
    <Field className="w-48">
      <FieldLabel>Event date</FieldLabel>
      <DateInput
        min={new Date(2025, 8, 1)}
        max={new Date(2025, 11, 31)}
        defaultValue={new Date(2026, 0, 9)}
        className="w-full"
      />
      <FieldDescription>Any day from September to December 2025.</FieldDescription>
    </Field>
  );
}
```

### Unavailable dates

`unavailable` takes the same matchers as [Calendar](https://ui.jarv.is/components/calendar.md)'s `unavailable`. The input
becomes invalid when its date matches one of them.

```tsx
import { DateInput } from "@/components/ui/date-input";
import { Field, FieldDescription, FieldLabel } from "@/components/ui/field";

export default function DateInputUnavailable() {
  return (
    <Field className="w-48">
      <FieldLabel>Delivery date</FieldLabel>
      <DateInput
        unavailable={{ dayOfWeek: [0, 6] }}
        defaultValue={new Date(2025, 5, 14)}
        className="w-full"
      />
      <FieldDescription>We deliver on weekdays.</FieldDescription>
    </Field>
  );
}
```

### In a form

Give the [`Field`](https://ui.jarv.is/components/field.md) or the input a `name`, and the value is submitted under it: a
date as `YYYY-MM-DD`, and a range as `YYYY-MM-DD/YYYY-MM-DD`, an ISO 8601 interval. When the input
is outside its form, pass the form's `id` as `form`. With `required`, the form won't submit without
a date, and validation fails with `valueMissing`. A range is submitted only once both its ends are
filled in. A partly typed date, a date that doesn't exist, or one outside `min`, `max` or
`unavailable` also blocks submission, failing with `customError`. A `FieldError` that matches
`customError` shows the reason, in the text from `labels`. A form reset restores `defaultValue`.

```tsx
"use client";

import { Button } from "@/components/ui/button";
import { DateInput } from "@/components/ui/date-input";
import { Field, FieldDescription, FieldError, FieldLabel } from "@/components/ui/field";
import { Form } from "@/components/ui/form";
import { toast } from "@/components/ui/toast";

export default function DateInputForm() {
  return (
    <Form
      className="max-w-sm"
      onFormSubmit={(values) =>
        toast.add({ title: "Leave requested", description: `For ${values.leave}.` })
      }
    >
      <Field name="leave">
        <FieldLabel>Time off</FieldLabel>
        <DateInput mode="range" required className="w-full" />
        <FieldDescription>The first and last days you'll be away.</FieldDescription>
        <FieldError match="valueMissing">Enter the dates you'll be away.</FieldError>
        <FieldError match="customError" />
      </Field>
      <Button type="submit" variant="primary" className="self-start">
        Request leave
      </Button>
    </Form>
  );
}
```

### Sizes

`size` matches the sizes of [Button](https://ui.jarv.is/components/button.md), [Input](https://ui.jarv.is/components/input.md) and
[Select](https://ui.jarv.is/components/select.md).

```tsx
import { DateInput } from "@/components/ui/date-input";

const sizes = ["sm", "default", "lg"] as const;

export default function DateInputSizes() {
  return (
    <div className="flex flex-wrap items-center gap-3">
      {sizes.map((size) => (
        <DateInput
          key={size}
          size={size}
          defaultValue={new Date(2025, 5, 12)}
          aria-label={`Date, ${size}`}
        />
      ))}
    </div>
  );
}
```

### Invalid

Set `invalid` on the `Field`, and explain the problem with a `FieldError`.

```tsx
import { DateInput } from "@/components/ui/date-input";
import { Field, FieldError, FieldLabel } from "@/components/ui/field";

export default function DateInputInvalid() {
  return (
    <Field invalid className="w-48">
      <FieldLabel>Renewal date</FieldLabel>
      <DateInput defaultValue={new Date(2024, 1, 2)} className="w-full" />
      <FieldError>Renew after the current plan ends.</FieldError>
    </Field>
  );
}
```

### Disabled

```tsx
import { DateInput } from "@/components/ui/date-input";

export default function DateInputDisabled() {
  return <DateInput disabled defaultValue={new Date(2025, 2, 14)} aria-label="Due date" />;
}
```

## Props

Children render at the end of the input, which is where [Date Picker](https://ui.jarv.is/components/date-picker.md) puts
the button that opens its calendar. The file also exports `formatDateValue`, which formats a date or
range the way the input submits it. It returns an empty string for a range that's missing either
end.

| Part | Extends |
| --- | --- |
| `DateInput` | `<div>` |

Base UI's [styling](https://base-ui.com/react/handbook/styling) and [composition](https://base-ui.com/react/handbook/composition) guides say more about `className`, `style` and `render`.

### DateInput

| Prop             | Type                                                                                                      | Default     | Description                                                                                                                                                                                                         |
| ---------------- | --------------------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mode?`          | `"range" \| "single"`                                                                                     | `"single"`  | Whether users type one date, or a range from a start date to an end date.                                                                                                                                           |
| `value?`         | `Date \| { from: Date; to: Date; } \| null`                                                               | —           | The date, or the range with `mode="range"`. `null` when there's none.                                                                                                                                               |
| `defaultValue?`  | `Date \| { from: Date; to: Date; } \| null`                                                               | `null`      |                                                                                                                                                                                                                     |
| `onValueChange?` | `((value: Date \| { from: Date; to: Date; } \| null, eventDetails: DateInputChangeEventDetails) => void)` | —           | Called when every part of the date is filled in, or every part of both dates in a range, and with `null` when a part is cleared or the date doesn't exist. Calling `eventDetails.cancel()` keeps the previous date. |
| `onDraftChange?` | `((range: { from?: Date; to?: Date; }, eventDetails: DateInputChangeEventDetails) => void)`               | —           | Called as users type with `mode="range"`, with the dates typed so far, such as a start date with no end date yet.                                                                                                   |
| `min?`           | `Date`                                                                                                    | —           | The earliest date. Earlier dates are invalid.                                                                                                                                                                       |
| `max?`           | `Date`                                                                                                    | —           | The latest date. Later dates are invalid.                                                                                                                                                                           |
| `unavailable?`   | `DateInputMatcher[] \| DateInputMatcher`                                                                  | —           | Unavailable dates: dates, `{ from, to }` ranges, `{ before }`, `{ after }`, `{ dayOfWeek }` or a function that takes a date. A matching date is invalid.                                                            |
| `locale?`        | `string`                                                                                                  | `"en-US"`   | The locale, as a BCP 47 tag, which sets the order of the day, month and year, and the month names.                                                                                                                  |
| `labels?`        | `DateInputLabels`                                                                                         | —           | Replaces the parts' accessible names and the validation messages. Pass only the ones you want to change.                                                                                                            |
| `name?`          | `string`                                                                                                  | —           | The name the value is submitted under in a form: a date as `YYYY-MM-DD`, and a range as `YYYY-MM-DD/YYYY-MM-DD`.                                                                                                    |
| `form?`          | `string`                                                                                                  | —           | The `id` of the form to submit the value with, when the input isn't inside it.                                                                                                                                      |
| `required?`      | `boolean`                                                                                                 | `false`     | Whether the form can't be submitted without a date. A date that doesn't exist, falls outside `min` and `max`, or is `unavailable` also blocks submission.                                                           |
| `disabled?`      | `boolean`                                                                                                 | `false`     | Whether the input is disabled. A disabled `Field` disables it too.                                                                                                                                                  |
| `readOnly?`      | `boolean`                                                                                                 | `false`     | Whether the date is shown without letting users change it.                                                                                                                                                          |
| `size?`          | `"default" \| "lg" \| "sm"`                                                                               | `"default"` | The height: `sm` 24px, `default` 28px, `lg` 32px.                                                                                                                                                                   |
| `children?`      | `React.ReactNode`                                                                                         | —           | Content rendered after the date, such as a button that opens a popup.                                                                                                                                               |
| `className?`     | `string`                                                                                                  | —           | CSS class applied to the element.                                                                                                                                                                                   |
| `style?`         | `React.CSSProperties`                                                                                     | —           | Style applied to the element.                                                                                                                                                                                       |
| `render?`        | `ComponentRenderFn<HTMLProps, {}> \| React.ReactElement`                                                  | —           | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.                           |

### DateInputLabels

`labels` takes any of these, and uses the English default for the rest.

| Property           | Type                                        | Default                                  | Description                                                                                                                                           |
| ------------------ | ------------------------------------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `year?`            | `string`                                    | `"Year"`                                 | The year part's accessible name.                                                                                                                      |
| `month?`           | `string`                                    | `"Month"`                                | The month part's accessible name.                                                                                                                     |
| `day?`             | `string`                                    | `"Day"`                                  | The day part's accessible name.                                                                                                                       |
| `start?`           | `((part: string) => string)`                | —                                        | Returns the accessible name of a part of the range's start date, given the part's own name, as in `Start day`.                                        |
| `end?`             | `((part: string) => string)`                | —                                        | Returns the accessible name of a part of the range's end date, given the part's own name, as in `End day`.                                            |
| `empty?`           | `string`                                    | `"Empty"`                                | What screen readers announce for an empty part.                                                                                                       |
| `incomplete?`      | `string`                                    | `"Enter a complete date."`               | The validation message for a partly typed date.                                                                                                       |
| `incompleteStart?` | `string`                                    | `"Enter a complete start date."`         | The validation message for a partly typed start date in a range.                                                                                      |
| `incompleteEnd?`   | `string`                                    | `"Enter a complete end date."`           | The validation message for a partly typed end date in a range.                                                                                        |
| `nonexistent?`     | `((month: string, days: number) => string)` | —                                        | Returns the validation message for a date that doesn't exist, given its month and year formatted for the locale and the number of days in that month. |
| `outOfRange?`      | `((min: string, max: string) => string)`    | —                                        | Returns the validation message for a date outside `min` and `max`, given both formatted for the locale.                                               |
| `tooEarly?`        | `((min: string) => string)`                 | —                                        | Returns the validation message for a date before `min` when there's no `max`, given `min` formatted for the locale.                                   |
| `tooLate?`         | `((max: string) => string)`                 | —                                        | Returns the validation message for a date after `max` when there's no `min`, given `max` formatted for the locale.                                    |
| `unavailable?`     | `((date: string) => string)`                | —                                        | Returns the validation message for a date that `unavailable` matches, given the date formatted for the locale.                                        |
| `reversed?`        | `string`                                    | `"End the range on or after its start."` | The validation message for a range that ends before it starts.                                                                                        |
