# DateTimePicker

Native browser input for picking a date, time, or related value.

## Default

Source: CoreAI.

[Download source](/coreai-design-system/source/examples/components-datetimepicker--default.tsx)

```tsx
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.

import type { DateTimePickerProps } from "@coreai-ds/react-components";
import { Field } from "@coreai-ds/react-components";
import { DateTimePicker } from "@coreai-ds/react-components";
import * as React from 'react';

export const Default = (props: DateTimePickerProps) => {
    const styles = /* css */ `
      .date-time-picker-default-example__control {
        max-width: 300px;
      }
    `;
    return (<>
        <style>{styles}</style>
        <Field label="Select a date">
          <DateTimePicker className="date-time-picker-default-example__control" {...props}/>
        </Field>
      </>);
};

export default Default;
```

## API

Generated CoreAI prop summaries, not replacement type declarations. Most native DOM/event and ARIA props are omitted. `?` means optional; JSDoc shows defaults, deprecations, and conditional requirements. Defaults assume the standard CoreAI provider.

### DateTimePicker API

```ts
interface DateTimePickerProps {
  /**
   * Controls the colors and borders of the input.
   *
   * Note: 'filled-darker-shadow' and 'filled-lighter-shadow' are deprecated and will be removed in the future.
   * @default 'outline'
   */
  appearance?: "outline" | "filled-darker" | "filled-lighter" | "underline" | "filled-darker-shadow" | "filled-lighter-shadow";

  as?: "input";

  /**
   * Input can't have children.
   */
  children?: undefined;

  className?: string;

  /**
   * If set, shows an "x" button once there's a value to act on. If `defaultValue` is set, the
   * button resets the value back to `defaultValue`; otherwise it clears the value entirely.
   */
  clearable?: boolean;

  /**
   * Element after the input text, within the input border
   */
  contentAfter?: WithSlotShorthandValue<{ as?: "span"; } & Omit<Omit<DetailedHTMLProps<HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, "ref"> & { ref?: ((instance: HTMLSpanElement | null) => void) | RefObject<HTMLSpanElement> | null; }, "children"> & { children?: any; }> | null | undefined;

  /**
   * Element before the input text, within the input border
   */
  contentBefore?: WithSlotShorthandValue<{ as?: "span"; } & Omit<Omit<DetailedHTMLProps<HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, "ref"> & { ref?: ((instance: HTMLSpanElement | null) => void) | RefObject<HTMLSpanElement> | null; }, "children"> & { children?: any; }> | null | undefined;

  /**
   * Initial value for an uncontrolled component.
   */
  defaultValue?: Date;

  /**
   * Collapse the control to its content width when nothing is selected and
   * grow it with the typed/selected content. Only available when `label` is set.
   */
  dynamicWidth?: boolean;

  /**
   * The actual `<input>` element. `type="text"` will be automatically applied unless overridden.
   *
   * This is the "primary" slot, so native props specified directly on the `<Input>` will go here
   * (except `className` and `style`, which go to the `root` slot). The top-level `ref` will
   * also go here.
   */
  input?: ({ as?: "input"; } & Omit<Omit<DetailedHTMLProps<InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>, "ref"> & { ref?: ((instance: HTMLInputElement | null) => void) | RefObject<HTMLInputElement> | null; }, "children"> & { children?: undefined; }) | undefined;

  /**
   * Optional inline label rendered inside the control, before the value.
   */
  label?: string;

  /**
   * The maximum allowable value.
   */
  max?: Date;

  /**
   * The minimum allowable value.
   */
  min?: Date;

  /**
   * Called when the user changes the value.
   */
  onChange?: ((event: ChangeEvent<HTMLInputElement>, data: DateTimePickerOnChangeData) => void);

  /**
   * Called after every `onChange` with the native constraint-validation result, derived from
   * the input's `ValidityState`, so `min`/`max`/`required`/malformed-input are all covered
   * without re-deriving them from the `Date` value. Pair with `Field`'s `validationState`/
   * `validationMessage` to surface it (Fluent's `Input` already themes `aria-invalid` for you).
   */
  onValidationResult?: ((event: ChangeEvent<HTMLInputElement>, data: DateTimePickerValidationResultData) => void);

  ref?: Ref<HTMLInputElement>;

  /**
   * Wrapper element which visually appears to be the input and is used for borders, focus styling, etc.
   * (A wrapper is needed to properly position `contentBefore` and `contentAfter` relative to `input`.)
   *
   * The root slot receives the `className` and `style` specified directly on the `<Input>`.
   * All other top-level native props will be applied to the primary slot, `input`.
   */
  root?: NonNullable<WithSlotShorthandValue<{ as?: "span"; } & Omit<Omit<DetailedHTMLProps<HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, "ref"> & { ref?: ((instance: HTMLSpanElement | null) => void) | RefObject<HTMLSpanElement> | null; }, "children"> & { children?: any; }> | null> | undefined;

  /**
   * Size of the input (changes the font size and spacing).
   * @default 'medium'
   */
  size?: "small" | "medium" | "large";

  style?: CSSProperties;

  /**
   * Controls text overflow behavior for the value. When true, long text is truncated with an ellipsis.
   */
  truncateTextOverflow?: boolean;

  /**
   * Which native temporal input to render.
   * @default 'date'
   */
  type?: "time" | "date" | "datetime-local" | "month" | "week";

  /**
   * Current value. Provide this for a controlled component; otherwise use `defaultValue`.
   */
  value?: Date | null;
}
```

## Implementation

CoreAI 0.12.0; Fluent 9.74.9.

[Setup and dependencies](/coreai-design-system/guides/Package.md).

Import components from `@coreai-ds/react-components`. CoreAI guidance above takes precedence over API demonstration examples.

## Clearable

Source: CoreAI.

[Download source](/coreai-design-system/source/examples/components-datetimepicker--clearable.tsx)

```tsx
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.

import * as React from 'react';
import { Field } from "@coreai-ds/react-components";
import { DateTimePicker } from "@coreai-ds/react-components";

export const Clearable = () => {
    const [value, setValue] = React.useState<Date | null>(new Date(2026, 6, 1));
    const styles = /* css */ `
      .date-time-picker-clearable-example__control {
        max-width: 300px;
      }
    `;
    return (<>
        <style>{styles}</style>
        <Field label="Select a date" hint={value ? `Selected: ${value.toDateString()}` : 'No date selected'}>
          <DateTimePicker className="date-time-picker-clearable-example__control" clearable value={value} onChange={(_ev, data) => setValue(data.value)}/>
        </Field>
      </>);
};

export default Clearable;
```

## Clearable With Default

Source: CoreAI.

[Download source](/coreai-design-system/source/examples/components-datetimepicker--clearable-with-default.tsx)

```tsx
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.

import { Field } from "@coreai-ds/react-components";
import { DateTimePicker } from "@coreai-ds/react-components";
import * as React from 'react';

export const ClearableWithDefault = () => {
    const styles = /* css */ `
      .date-time-picker-clearable-default-example__control {
        max-width: 300px;
      }
    `;
    return (<>
        <style>{styles}</style>
        <Field label="Select a date" hint="Resets to July 1, 2026 instead of clearing">
          <DateTimePicker className="date-time-picker-clearable-default-example__control" clearable defaultValue={new Date(2026, 6, 1)}/>
        </Field>
      </>);
};

export default ClearableWithDefault;
```

## Controlled

Source: CoreAI.

[Download source](/coreai-design-system/source/examples/components-datetimepicker--controlled.tsx)

```tsx
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.

import type { DateTimePickerErrorType } from "@coreai-ds/react-components";
import * as React from 'react';
import { Field } from "@coreai-ds/react-components";
import { DateTimePicker } from "@coreai-ds/react-components";

export const Controlled = () => {
    const validationMessages: Record<DateTimePickerErrorType, string> = {
        'required-input': 'A date is required.',
        'out-of-bounds': 'Date must be within the allowed range.',
        'invalid-input': "That date isn't valid.",
    };
    const min = new Date(2026, 0, 1);
    const max = new Date(2026, 11, 31);
    const [value, setValue] = React.useState<Date | null>(new Date(2026, 6, 1));
    const [error, setError] = React.useState<DateTimePickerErrorType>();
    const styles = /* css */ `
      .date-time-picker-controlled-example__control {
        max-width: 300px;
      }
    `;
    return (<>
        <style>{styles}</style>
        <Field label="Select a date in 2026" hint={error ? undefined : value ? `Selected: ${value.toDateString()}` : 'No date selected'} required validationState={error ? 'error' : 'none'} validationMessage={error && validationMessages[error]}>
          <DateTimePicker className="date-time-picker-controlled-example__control" value={value} min={min} max={max} onChange={(_ev, data) => setValue(data.value)} onValidationResult={(_ev, data) => setError(data.error)}/>
        </Field>
      </>);
};

export default Controlled;
```

## Date And Time

Source: CoreAI.

[Download source](/coreai-design-system/source/examples/components-datetimepicker--date-and-time.tsx)

```tsx
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.

import { Field } from "@coreai-ds/react-components";
import { DateTimePicker } from "@coreai-ds/react-components";
import * as React from 'react';

export const DateAndTime = () => {
    const styles = /* css */ `
      .date-time-picker-date-time-example__control {
        max-width: 300px;
      }
    `;
    return (<>
        <style>{styles}</style>
        <Field label="Select a date and time">
          <DateTimePicker type="datetime-local" className="date-time-picker-date-time-example__control"/>
        </Field>
      </>);
};

export default DateAndTime;
```

## Month

Source: CoreAI.

[Download source](/coreai-design-system/source/examples/components-datetimepicker--month.tsx)

```tsx
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.

import { Field } from "@coreai-ds/react-components";
import { DateTimePicker } from "@coreai-ds/react-components";
import * as React from 'react';

export const Month = () => {
    const styles = /* css */ `
      .date-time-picker-month-example__control {
        max-width: 300px;
      }
    `;
    return (<>
        <style>{styles}</style>
        <Field label="Select a month">
          <DateTimePicker type="month" className="date-time-picker-month-example__control"/>
        </Field>
      </>);
};

export default Month;
```

## Range

Source: CoreAI.

[Download source](/coreai-design-system/source/examples/components-datetimepicker--range.tsx)

```tsx
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.

import type { DateTimePickerErrorType } from "@coreai-ds/react-components";
import * as React from 'react';
import { Field } from "@coreai-ds/react-components";
import { DateTimePicker } from "@coreai-ds/react-components";

export const Range = () => {
    const validationMessages: Record<DateTimePickerErrorType, string> = {
        'required-input': 'A date is required.',
        'out-of-bounds': 'Date must be within the allowed range.',
        'invalid-input': "That date isn't valid.",
    };
    const [start, setStart] = React.useState<Date | null>(new Date(2026, 6, 1));
    const [end, setEnd] = React.useState<Date | null>(new Date(2026, 6, 10));
    const [startError, setStartError] = React.useState<DateTimePickerErrorType>();
    const [endError, setEndError] = React.useState<DateTimePickerErrorType>();
    const dayCount = start && end ? Math.round((end.getTime() - start.getTime()) / 86400000) + 1 : undefined;
    const styles = /* css */ `
      .date-time-picker-range-example__row {
        display: flex;
        gap: var(--spacingHorizontalM);
        align-items: flex-start;
      }

      .date-time-picker-range-example__control {
        max-width: 300px;
      }
    `;
    return (<>
        <style>{styles}</style>
        <div className="date-time-picker-range-example">
          <div className="date-time-picker-range-example__row">
            <Field label="Start date" validationState={startError ? 'error' : 'none'} validationMessage={startError && validationMessages[startError]}>
              <DateTimePicker className="date-time-picker-range-example__control" value={start} max={end ?? undefined} onChange={(_ev, data) => setStart(data.value)} onValidationResult={(_ev, data) => setStartError(data.error)}/>
            </Field>
            <Field label="End date" validationState={endError ? 'error' : 'none'} validationMessage={endError && validationMessages[endError]}>
              <DateTimePicker className="date-time-picker-range-example__control" value={end} min={start ?? undefined} onChange={(_ev, data) => setEnd(data.value)} onValidationResult={(_ev, data) => setEndError(data.error)}/>
            </Field>
          </div>
          <p>
            {dayCount !== undefined
            ? `${dayCount} day${dayCount === 1 ? '' : 's'} selected`
            : 'Select both dates'}
          </p>
        </div>
      </>);
};

export default Range;
```

## Time

Source: CoreAI.

[Download source](/coreai-design-system/source/examples/components-datetimepicker--time.tsx)

```tsx
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.

import { Field } from "@coreai-ds/react-components";
import { DateTimePicker } from "@coreai-ds/react-components";
import * as React from 'react';

export const Time = () => {
    const styles = /* css */ `
      .date-time-picker-time-example__control {
        max-width: 300px;
      }
    `;
    return (<>
        <style>{styles}</style>
        <Field label="Select a time">
          <DateTimePicker type="time" className="date-time-picker-time-example__control"/>
        </Field>
      </>);
};

export default Time;
```

## Week

Source: CoreAI.

[Download source](/coreai-design-system/source/examples/components-datetimepicker--week.tsx)

```tsx
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.

import { Field } from "@coreai-ds/react-components";
import { DateTimePicker } from "@coreai-ds/react-components";
import * as React from 'react';

export const Week = () => {
    const styles = /* css */ `
      .date-time-picker-week-example__control {
        max-width: 300px;
      }
    `;
    return (<>
        <style>{styles}</style>
        <Field label="Select a week">
          <DateTimePicker type="week" className="date-time-picker-week-example__control"/>
        </Field>
      </>);
};

export default Week;
```