# Date Picker
> Date Picker component enables users to enter a date either through text input or selecting a date from the Calendar dropdown.

## Import

```js
import { DatePicker } from '@gemini-suite/vera-react';

// you may also access Date Picker's context via hook:
// import { useDatePickerContext } from '@gemini-suite/vera-react';
```

Date Picker is a compound component that consists of multiple parts:

- `DatePicker.Root`: The wrapper that contains all the parts of a date picker and provides context for its children.
- `DatePicker.TextInput`: A [Text Input](/components/forms/text-input) that allows users to input date as text.
- `DatePicker.CalendarTrigger`: The trigger that opens `DatePicker.Calendar`.
- `DatePicker.Calendar`: The calendar that enables users to select and view dates. Composes [Popover](/components/popover) and [Calendar](/components/calendar) components under the hood.
- `DatePicker.Clear`: The button that clears the user selection.

## Examples

### Basic

By default, the `DatePicker` is uncontrolled and the calendar's initial view is set to current month.

Users can enter a date either through text input or open a calendar popover to select dates in a standard month grid.

<Callout variant="tip">

By default, the expected text input format (as shown in the placeholder) is localised to the user's browser locale.
`DatePicker` parses the text typed into the field internally and splits it into appropriate date segments according to the detected format.

`DatePicker` supports partial input and automatically detects incorrect input. If one of the date segments is invalid, it will fallback to the last valid segment value.
This ensures that no extra effort is needed on the consumer side to handle input that cannot be converted into a date.

</Callout>

```jsx
<DatePicker.Root>
  <DatePicker.TextInput
    aria-label="Choose a date"
    trailingVisual={<DatePicker.CalendarTrigger aria-label="Use calendar" />}
  />
  <DatePicker.Calendar />
</DatePicker.Root>
```

You can pass `defaultValue` for uncontrolled `DatePicker`.

```jsx
<DatePicker.Root
  defaultValue={new Date(2022, 5, 11)}
  onValueChange={date => {
    console.log(`Date changed to ${date}`);
  }}
>
  <DatePicker.TextInput
    aria-label="Pick a date"
    trailingVisual={<DatePicker.CalendarTrigger aria-label="Use calendar" />}
  />
  <DatePicker.Calendar />
</DatePicker.Root>
```

### Controlled

You can easily make the `DatePicker` controlled, by passing your own state to `value` prop. `onValueChange` handler is called when
the date value changes, allowing you to sync state.

<Callout variant="tip">

The component returns dates in [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) format or `null` to indicate no selection. You must take care of conversion to the desired format yourself.

For [simple locale-respective date formatting](https://rafaelcamargo.com/blog/mastering-date-formatting-using-intl-date-time-format-in-javascript/) we recommend using the native `Intl` API. `useDateFormatter` hook exported by Vera accepts same arguments as `Intl.DateTimeFormat` constructor and returns a memoized instance of it.

Alternatively you can use a date-management library such as [date-fns](https://date-fns.org/), which has multiple utility
functions including `format`.

</Callout>

```jsx
() => {
  const [date, setDate] = React.useState(new Date('1990-01-01'));
  const formatter = useDateFormatter();

  return (
    <Flex flow="column">
      <DatePicker.Root value={date} onValueChange={setDate}>
        <DatePicker.TextInput
          aria-label="Choose a date"
          trailingVisual={
            <DatePicker.CalendarTrigger aria-label="Use calendar" />
          }
        />
        <DatePicker.Calendar />
      </DatePicker.Root>
      <Box>{date ? `Selected date: ${formatter.format(date)}` : null}</Box>
    </Flex>
  );
};
```

### With Form Field

Use `DatePicker` with [Form Field](/components/forms/form-field) in order to enhance layout with a clear label. Optionally, you may want to connect helper text and/or validation feedback message to the `DatePicker`.

<Callout variant="tip">

When using `DatePicker` without `FormField.Label`, be mindful to provide `aria-label` instead.

</Callout>

```jsx
() => {
  const [birthday, setBirthday] = React.useState(null);

  return (
    <Flex flow="column">
      <FormField.Root as={Flex} flow="column">
        <FormField.Label>{'Date'}</FormField.Label>
        <FormField.HelperText>
          {'Please enter a publish date.'}
        </FormField.HelperText>
        <DatePicker.Root>
          <DatePicker.TextInput
            trailingVisual={
              <DatePicker.CalendarTrigger aria-label="Use calendar" />
            }
          />
          <DatePicker.Calendar />
        </DatePicker.Root>
      </FormField.Root>
      <FormField.Root
        as={Flex}
        flow="column"
        isRequired
        validationStatus={!birthday ? 'error' : undefined}
      >
        <FormField.Label>{'Your birthday'}</FormField.Label>
        <DatePicker.Root value={birthday} onValueChange={setBirthday}>
          <DatePicker.TextInput
            trailingVisual={
              <DatePicker.CalendarTrigger aria-label="Use calendar" />
            }
          />
          <DatePicker.Calendar />
        </DatePicker.Root>
        <FormField.FeedbackMessage>
          <FormField.FeedbackIcon />
          {'Feedback message.'}
        </FormField.FeedbackMessage>
      </FormField.Root>
    </Flex>
  );
};
```

### Validation

Since `DatePicker` allows user to enter a date through a text input, it has to handle invalid user input, i.e. not meeting the expected date format or providing a date that falls out of min/max bounds.

By default, `DatePicker` attempts to parse the provided input into a valid `Date` object according to the expected format as shown in the placeholder.
If that fails, the text field will highlight itself in red to provide visual cue that it needs correction.
You can subscribe to the `onError` callback which is triggered when the input error changes and use the
`FormField.FeedbackMessage` to communicate a detailed error message to the user.

<Callout variant="tip">

`onError` callback provides a reason for the error which can be either an incorrect date or a date outside of the specified `minDate` or `maxDate` range.

</Callout>

```jsx
() => {
  const [error, setError] = React.useState(null);

  const currentYear = new Date().getFullYear();

  const errorMessage = React.useMemo(() => {
    switch (error) {
      case 'maxDate':
      case 'minDate': {
        return `Please select a date from the year ${currentYear}.`;
      }

      case 'invalidDate': {
        return 'Your date is not valid.';
      }

      default: {
        return '';
      }
    }
  }, [error]);

  return (
    <FormField.Root
      as={Flex}
      flow="column"
      validationStatus={error ? 'error' : undefined}
    >
      <FormField.Label>{`Favorite day of ${currentYear}`}</FormField.Label>
      <FormField.HelperText>
        {'Type in invalid date to see the error message.'}
      </FormField.HelperText>
      <DatePicker.Root
        minDate={startOfYear(new Date())}
        maxDate={endOfYear(new Date())}
        onError={newError => setError(newError)}
      >
        <DatePicker.TextInput
          trailingVisual={
            <DatePicker.CalendarTrigger aria-label="Use calendar" />
          }
        />
        <DatePicker.Calendar />
      </DatePicker.Root>
      <FormField.FeedbackMessage>
        <FormField.FeedbackIcon />
        {errorMessage}
      </FormField.FeedbackMessage>
    </FormField.Root>
  );
};
```

Alternatively, you may want to prevent entering incorrect values through `DatePicker.TextInput` altogether. When `shouldAutoCorrectInput` is set to `true`, `DatePicker` will handle partial user input,
automatically cap the input to the specified limits and revert to the last correct date after user typed an incorrect value. `onError` callback will not be fired as no error messaging is needed in that case.

```jsx
() => {
  const currentYear = new Date().getFullYear();

  return (
    <FormField.Root as={Flex} flow="column">
      <FormField.Label>{`Favorite day of ${currentYear}`}</FormField.Label>
      <FormField.HelperText>
        {
          'Type in partial or invalid date to see the auto-correction in action.'
        }
      </FormField.HelperText>
      <DatePicker.Root
        shouldAutoCorrectInput
        minDate={startOfYear(new Date())}
        maxDate={endOfYear(new Date())}
      >
        <DatePicker.TextInput
          trailingVisual={
            <DatePicker.CalendarTrigger aria-label="Use calendar" />
          }
        />
        <DatePicker.Calendar />
      </DatePicker.Root>
    </FormField.Root>
  );
};
```

### Disabled state

Pass `isDisabled` prop to the accompanying `FormField` and it will cascade down to the `DatePicker`.

```jsx
<FormField.Root as={Flex} flow="column" isDisabled>
  <FormField.Label>{'Choose a date'}</FormField.Label>
  <DatePicker.Root>
    <DatePicker.TextInput
      trailingVisual={<DatePicker.CalendarTrigger aria-label="Use calendar" />}
    />
    <DatePicker.Calendar />
  </DatePicker.Root>
</FormField.Root>
```

You can also pass `isDisabled` prop directly to `DatePicker`.

```jsx
<DatePicker.Root isDisabled>
  <DatePicker.TextInput
    aria-label="Choose a date"
    trailingVisual={<DatePicker.CalendarTrigger aria-label="Use calendar" />}
  />
  <DatePicker.Calendar />
</DatePicker.Root>
```

### Size

As with other types of input controls, we offer the ability to change the `size` property.
`medium` and `small` sizes are available, with the `medium` size used by default.

```jsx
<Flex flow="column">
  <FormField.Root as={Flex} flow="column" size="small">
    <FormField.Label>{'Small'}</FormField.Label>
    <DatePicker.Root size="small">
      <DatePicker.TextInput
        trailingVisual={
          <DatePicker.CalendarTrigger aria-label="Use calendar" />
        }
      />
      <DatePicker.Calendar />
    </DatePicker.Root>
  </FormField.Root>
  <FormField.Root as={Flex} flow="column">
    <FormField.Label>{'Medium'}</FormField.Label>
    <DatePicker.Root>
      <DatePicker.TextInput
        trailingVisual={
          <DatePicker.CalendarTrigger aria-label="Use calendar" />
        }
      />
      <DatePicker.Calendar />
    </DatePicker.Root>
  </FormField.Root>
</Flex>
```

### Min/max date

It's possible to cap the date range that can be selected.

`DatePicker.Calendar` will display non-selectable dates as disabled and constrain the navigation forward/backward in time.
Dates typed into `DatePicker.TextInput` that are out of specified limits will trigger `onError` callback or get automatically capped when `shouldAutoCorrectInput` is `true`.

<Callout variant="tip">

If you don't supply a default date when using the `minDate`/`maxDate` props and `today` falls outside of the range limits it gets automatically constrained to either min or max.

</Callout>

```jsx
<Flex flow="column">
  <FormField.Root as={Flex} flow="column">
    <FormField.Label>{'Favorite day of current year'}</FormField.Label>
    <DatePicker.Root
      minDate={startOfYear(new Date())}
      maxDate={endOfYear(new Date())}
    >
      <DatePicker.TextInput
        trailingVisual={
          <DatePicker.CalendarTrigger aria-label="Use calendar" />
        }
      />
      <DatePicker.Calendar />
    </DatePicker.Root>
  </FormField.Root>
  <FormField.Root as={Flex} flow="column">
    <FormField.Label>{'Favorite day of 2022'}</FormField.Label>
    <DatePicker.Root
      minDate={new Date('2022-01-01')}
      maxDate={new Date('2022-12-31')}
    >
      <DatePicker.TextInput
        trailingVisual={
          <DatePicker.CalendarTrigger aria-label="Use calendar" />
        }
      />
      <DatePicker.Calendar />
    </DatePicker.Root>
  </FormField.Root>
  <FormField.Root as={Flex} flow="column">
    <FormField.Label>{'Pick a day before 28th July 2022'}</FormField.Label>
    <DatePicker.Root maxDate={new Date(2022, 6, 28)}>
      <DatePicker.TextInput
        trailingVisual={
          <DatePicker.CalendarTrigger aria-label="Use calendar" />
        }
      />
      <DatePicker.Calendar />
    </DatePicker.Root>
  </FormField.Root>
</Flex>
```

When choosing range that spans over several years, calendar automatically displays [Select Menus](/components/select-menu) for month/year,
to let the user more easily find the period they want to choose from without having to cycle through multiple months.

```jsx
<Flex flow="column">
  <FormField.Root as={Flex} flow="column">
    <FormField.Label>
      {'Pick a day between 5 years in the past and future'}
    </FormField.Label>
    <DatePicker.Root
      minDate={new Date(new Date().getFullYear() - 5, 0, 1)}
      maxDate={new Date(new Date().getFullYear() + 5, 11, 31)}
    >
      <DatePicker.TextInput
        trailingVisual={
          <DatePicker.CalendarTrigger aria-label="Use calendar" />
        }
      />
      <DatePicker.Calendar />
    </DatePicker.Root>
  </FormField.Root>
  <FormField.Root as={Flex} flow="column">
    <FormField.Label>{'Pick a day between August and October'}</FormField.Label>
    <DatePicker.Root
      minDate={new Date(new Date().getFullYear(), 7, 1)}
      maxDate={new Date(new Date().getFullYear(), 9, 30)}
    >
      <DatePicker.TextInput
        trailingVisual={
          <DatePicker.CalendarTrigger aria-label="Use calendar" />
        }
      />
      <DatePicker.Calendar />
    </DatePicker.Root>
  </FormField.Root>
</Flex>
```

When only a subset of days within a month is available to choose from, both year/month selects and navigation buttons are not shown.

```jsx
<FormField.Root as={Flex} flow="column">
  <FormField.Label>
    {'Pick a day between 5th and 20th September'}
  </FormField.Label>
  <DatePicker.Root
    minDate={new Date(new Date().getFullYear(), 8, 5)}
    maxDate={new Date(new Date().getFullYear(), 8, 20)}
  >
    <DatePicker.TextInput
      trailingVisual={<DatePicker.CalendarTrigger aria-label="Use calendar" />}
    />
    <DatePicker.Calendar />
  </DatePicker.Root>
</FormField.Root>
```

### Date range

`DatePicker` allows user to pick a single date, but date range selection can easily be implemented
by using controlled "from" and "to" date pickers.

By using [modifiers](https://react-day-picker.js.org/basics/modifiers) on the `DatePicker.Calendar`, we are able to visually highlight the selected date range in both pickers.

```jsx
() => {
  const [fromDate, setFromDate] = React.useState(null);
  const [toDate, setToDate] = React.useState(null);

  const modifiers = React.useMemo(() => {
    if (!fromDate || !toDate) {
      return;
    }

    return {
      range_start: fromDate,
      range_end: toDate,
      range_middle: isSameDay(fromDate, toDate)
        ? false
        : {
            after: fromDate,
            before: toDate
          }
    };
  }, [fromDate, toDate]);

  return (
    <Flex wrap="wrap">
      <FormField.Root as={Flex} flow="column">
        <FormField.Label>{'Date from'}</FormField.Label>
        <DatePicker.Root
          value={fromDate}
          onValueChange={setFromDate}
          maxDate={toDate}
        >
          <DatePicker.TextInput
            trailingVisual={
              <DatePicker.CalendarTrigger aria-label="Use calendar" />
            }
          />
          <DatePicker.Calendar modifiers={modifiers} />
        </DatePicker.Root>
      </FormField.Root>
      <FormField.Root as={Flex} flow="column">
        <FormField.Label>{'Date to'}</FormField.Label>
        <DatePicker.Root
          value={toDate}
          onValueChange={setToDate}
          minDate={fromDate}
        >
          <DatePicker.TextInput
            trailingVisual={
              <DatePicker.CalendarTrigger aria-label="Use calendar" />
            }
          />
          <DatePicker.Calendar modifiers={modifiers} />
        </DatePicker.Root>
      </FormField.Root>
    </Flex>
  );
};
```

If you don't need the flexibility of manual date range input and the user is more likely to select a more narrow scope, it's possible to use a single range picker control by composing [Popover](/components/popover), [Button](/components/button) and [Calendar](/components/calendar) components.

<Callout variant="tip">

Displaying two months makes it easier for users to select date ranges that span across both.

</Callout>

```jsx
() => {
  const today = new Date();
  const [range, setRange] = React.useState({
    from: new Date(today.getFullYear(), 9, 10),
    to: new Date(today.getFullYear(), 10, 10)
  });
  const [isOpen, setIsOpen] = React.useState(false);

  const formatter = useDateFormatter();

  return (
    <Popover.Root isOpen={isOpen} onIsOpenChange={setIsOpen}>
      <Popover.Trigger
        as={Button}
        size={size}
        variant="outline"
        leftIcon={<SvgIcon iconName="calendar" />}
      >
        <Text color={range ? 'foregroundNeutral' : undefined}>
          {range?.from
            ? range.to
              ? formatter.formatRange(range.from, range.to)
              : formatter.format(range.from)
            : 'Select date range'}
        </Text>
      </Popover.Trigger>
      <Popover.Content padding="spacingM" placement="top_left">
        <Flex flow="column" cross="start">
          <Calendar
            autoFocus
            mode="range"
            numberOfMonths={2}
            onSelect={range => {
              setRange(range);

              if (!range) {
                setIsOpen(false);
              }
            }}
            defaultMonth={range?.from}
            selected={range}
            captionLayout="dropdown"
            startMonth={new Date(today.getFullYear() - 1, 0)}
            endMonth={new Date(today.getFullYear() + 1, 11)}
          />
          <Button
            isDisabled={!range}
            variant="outline"
            onClick={() => {
              setRange(undefined);
              setIsOpen(false);
            }}
          >
            {'Clear'}
          </Button>
        </Flex>
      </Popover.Content>
    </Popover.Root>
  );
};
```

### Enforcing a locale

If you want to enforce a locale, you can pass it as a prop. This will override the user's browser locale.
`locale` property expects a [date-fns locale object](https://date-fns.org/docs/Locale).

For example, to localize the calendar and text input format in German, import the locale object from [date-fns](https://date-fns.org/) and pass it to the component.

```js
import { de } from 'date-fns/locale';
// import { enGB, nb, ... } from 'date-fns/locale';
```

```jsx
() => {
  const minDate = new Date(new Date().setMonth(new Date().getMonth() - 3));
  const maxDate = new Date(new Date().setMonth(new Date().getMonth() + 3));

  return (
    <Flex flow="column">
      <FormField.Root as={Flex} flow="column">
        <FormField.Label>{'English date picker'}</FormField.Label>
        <DatePicker.Root locale={enGB}>
          <DatePicker.TextInput
            trailingVisual={
              <DatePicker.CalendarTrigger aria-label="Use calendar" />
            }
          />
          <DatePicker.Calendar />
        </DatePicker.Root>
      </FormField.Root>
      <FormField.Root as={Flex} flow="column">
        <FormField.Label>{'German date picker'}</FormField.Label>
        <DatePicker.Root locale={de}>
          <DatePicker.TextInput
            trailingVisual={
              <DatePicker.CalendarTrigger aria-label="Use calendar" />
            }
          />
          <DatePicker.Calendar />
        </DatePicker.Root>
      </FormField.Root>
      <FormField.Root as={Flex} flow="column">
        <FormField.Label>{'Norwegian date picker'}</FormField.Label>
        <DatePicker.Root locale={nb} minDate={minDate} maxDate={maxDate}>
          <DatePicker.TextInput
            trailingVisual={
              <DatePicker.CalendarTrigger aria-label="Use calendar" />
            }
          />
          <DatePicker.Calendar />
        </DatePicker.Root>
      </FormField.Root>
    </Flex>
  );
};
```

### Enforcing a time zone

To change the time zone, pass [IANA time zone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) identifier or a UTC offset to `timeZone` prop.

<Callout variant="important">

When working with time zones, make sure to use `TZDate` object from [date-fns timezone utils](https://date-fns.org/v4.1.0/docs/Time-Zones) instead of the native `Date` object.

</Callout>

```js
import { TZDate } from '@date-fns/tz';
```

```jsx
() => {
  const [timeZone, setTimeZone] = React.useState('America/Los_Angeles');
  const [selected, setSelected] = React.useState(
    new TZDate(new Date(), timeZone) // Make sure you use `TZDate` instead of `Date`
  );

  const handleTimeZoneChange = timeZone => {
    setTimeZone(timeZone);
    setSelected(new TZDate(selected, timeZone));
  };

  return (
    <Flex flow="column">
      <FormField.Root as={Flex} flow="column">
        <FormField.Label as="div">{'Time zone'}</FormField.Label>
        <SingleSelectMenu.Root
          value={timeZone}
          onValueChange={handleTimeZoneChange}
        >
          <SingleSelectMenu.Trigger css={{ maxWidth: 286 }} />
          <SingleSelectMenu.Content>
            <SingleSelectMenu.Item value="America/Los_Angeles">
              {'America/Los_Angeles'}
            </SingleSelectMenu.Item>
            <SingleSelectMenu.Item value="Europe/Berlin">
              {'Europe/Berlin'}
            </SingleSelectMenu.Item>
            <SingleSelectMenu.Item value="+12:00">
              {'+12:00'}
            </SingleSelectMenu.Item>
          </SingleSelectMenu.Content>
        </SingleSelectMenu.Root>
      </FormField.Root>
      <FormField.Root as={Flex} flow="column">
        <FormField.Label>{'Date with time zone'}</FormField.Label>
        <DatePicker.Root
          timeZone={timeZone}
          value={selected}
          onValueChange={setSelected}
        >
          <DatePicker.TextInput
            trailingVisual={
              <DatePicker.CalendarTrigger aria-label="Use calendar" />
            }
          />
          <DatePicker.Calendar />
        </DatePicker.Root>
      </FormField.Root>
      <Text>
        {selected
          ? selected.toString()
          : `Pick a day to see it in ${timeZone} time zone.`}
      </Text>
    </Flex>
  );
};
```

### Custom trigger

By leveraging individual parts of the `DatePicker`, it's possible to build custom solutions based on how you want the user to be able to select a date.

For example, a `DatePicker` without `DatePicker.TextInput` that uses [Button](/components/button) displaying currently selected date as a `DatePicker.CalendarTrigger`.
`DatePicker.Clear` is included in the calendar's footer to provide the ability to clear the active selection.

```jsx
() => {
  const [date, setDate] = React.useState(null);
  const formatter = useDateFormatter('en', {
    day: 'numeric',
    year: 'numeric',
    month: 'long'
  });

  return (
    <DatePicker.Root
      value={date}
      onValueChange={setDate}
      minDate={new Date('2023-01-01')}
      maxDate={new Date('2023-12-31')}
    >
      <DatePicker.CalendarTrigger
        as={Button}
        variant="outline"
        leftIcon={<SvgIcon iconName="calendar" />}
      >
        {date ? (
          <Text color="foregroundNeutral">{formatter.format(date)}</Text>
        ) : (
          'Choose a date'
        )}
      </DatePicker.CalendarTrigger>
      <DatePicker.Calendar
        footer={
          date ? (
            <DatePicker.Clear
              as={Button}
              variant="outline"
              marginTop="spacingM"
            >
              {'Clear'}
            </DatePicker.Clear>
          ) : null
        }
      />
    </DatePicker.Root>
  );
};
```

---

## Accessibility features

<ul>
  <li iconName="check">

`DatePicker` provides deep keyboard interactions.

  </li>
  <li iconName="check">

Necessary ARIA roles and attributes are provided to give directions to a screen reader user.

  </li>
</ul>

---

## API Reference

### DatePicker

| Name                     | Type                                                          | Default    | Description                                                                                                                | Required |
| ------------------------ | ------------------------------------------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------- | -------- |
| `defaultValue`           | `Date`                                                        |            | The initially selected date when component is first rendered. Use when you do not need to control the state of the picker. |          |
| `value`                  | `Date \| null`                                                |            | The controlled value of the selected date. Use in conjunction with `onValueChange`.                                        |          |
| `onValueChange`          | `(date: Date \| null) => void`                                |            | Event handler called when the selected date changes.                                                                       |          |
| `minDate`                | `Date \| null`                                                |            | Controls the maximum available date.                                                                                       |          |
| `maxDate`                | `Date \| null`                                                |            | Controls the minimum available date.                                                                                       |          |
| `size`                   | `"medium" \| "small"`                                         | `"medium"` | The size of the date picker.                                                                                               |          |
| `locale`                 | `Locale`                                                      |            | The [date-fns locale object](https://date-fns.org/docs/Locale) used to localize the calendar and text input format.        |          |
| `timeZone`               | `string`                                                      |            | Time zone (IANA or UTC offset) for the calendar.                                                                           |          |
| `isDisabled`             | `boolean`                                                     |            | When `true`, the date picker will be disabled.                                                                             |          |
| `isRequired`             | `boolean`                                                     |            | When `true`, the date picker is marked as required.                                                                        |          |
| `shouldAutoCorrectInput` | `boolean`                                                     | `false`    | When `true`, the date picker will auto-correct invalid value entered by hand in the `DatePicker.TextInput`.                |          |
| `onError`                | `(error: DateValidationError \| null, value: string) => void` |            | Event handler called when the error associated to the user-typed value changes.                                            |          |

### DatePicker.TextInput

<Callout variant="tip">

In addition to the props below, you can pass [Text Input props](/components/forms/text-input#api-reference).

</Callout>

| Name             | Type              | Default | Description                                      | Required |
| ---------------- | ----------------- | ------- | ------------------------------------------------ | -------- |
| `trailingVisual` | `React.ReactNode` |         | Visual positioned on the right edge of the item. |          |

### DatePicker.CalendarTrigger

| Name  | Type                                                      | Default  | Description                                                                                                                                                                                                                                                                                  | Required |
| ----- | --------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `as`  | `keyof JSX.IntrinsicElements \| React.ComponentType<any>` | `button` | Change the component to a different HTML tag or custom component. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node.   For more details, read our [Composition](/get-started/composition#polymorphism) guide. |          |
| `css` | `StitchesCss`                                             |          | Apply styles directly to a component in a similar way how you would define inline styles. Vera uses [Stitches](https://stitches.dev/) under the hood with a fully-typed API and support for features like tokens, media queries, or variants.                                                |          |

### DatePicker.Calendar

<Callout variant="tip">

In addition to the props below, you can pass [Popover props](/components/popover#api-reference) and most of the [Calendar props](/components/calendar#api-reference).

</Callout>

| Name        | Type           | Default | Description                                                                                   | Required |
| ----------- | -------------- | ------- | --------------------------------------------------------------------------------------------- | -------- |
| `locale`    | `Locale`       |         | The [date-fns locale object](https://date-fns.org/docs/Locale) used to localize the calendar. |          |
| `timeZone`  | `string`       |         | Time zone for the calendar.                                                                   |          |
| `modifiers` | `DayModifiers` |         | Add [modifiers](https://react-day-picker.js.org/basics/modifiers) to the matching days.       |          |

### DatePicker.Clear

<Callout variant="tip">

In addition to the props below, you can pass [Box props](/components/layout/box#api-reference) to control the spacing.

</Callout>

| Name  | Type                                                      | Default  | Description                                                                                                                                                                                                                                                                                  | Required |
| ----- | --------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `as`  | `keyof JSX.IntrinsicElements \| React.ComponentType<any>` | `button` | Change the component to a different HTML tag or custom component. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node.   For more details, read our [Composition](/get-started/composition#polymorphism) guide. |          |
| `css` | `StitchesCss`                                             |          | Apply styles directly to a component in a similar way how you would define inline styles. Vera uses [Stitches](https://stitches.dev/) under the hood with a fully-typed API and support for features like tokens, media queries, or variants.                                                |          |