> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.

# DatePicker

Data Entry`@rockshin/tao-ui`

[Examples](#examples)[API](#api)

Lets users enter or choose a single date, with optional time selection.

## When to use

Use DatePicker when free text date input would be error-prone or when users benefit from calendar context.

**Recommended**

- Support keyboard entry for known dates.
- Use presets for common relative choices when helpful.

**Avoid**

- Do not force calendar navigation for dates far in the past without typed input.

## Examples


### Basic usage
```tsx preview
import { DatePicker, FormField } from '@rockshin/tao-ui';
import type { Dayjs } from 'dayjs';
import { useState } from 'react';

function DatePickerExample() {
  const [value, setValue] = useState<Dayjs | null>(null);

  return (
    <FormField label="Start date">
      <DatePicker
        value={value}
        onChange={setValue}
        placeholder="Select a date"
      />
    </FormField>
  );
}

export default DatePickerExample;
```

### Picker modes
```tsx preview
import { DatePicker, Stack } from '@rockshin/tao-ui';
import type { Dayjs } from 'dayjs';
import { useState } from 'react';

function DatePickerModes() {
  const [date, setDate] = useState<Dayjs | null>(null);
  const [month, setMonth] = useState<Dayjs | null>(null);
  const [year, setYear] = useState<Dayjs | null>(null);

  return (
    <Stack gap="md" style={{ maxWidth: 320 }}>
      <DatePicker
        value={date}
        onChange={setDate}
        picker="date"
        placeholder="Select date"
      />
      <DatePicker
        value={month}
        onChange={setMonth}
        picker="month"
        placeholder="Select month"
      />
      <DatePicker
        value={year}
        onChange={setYear}
        picker="year"
        placeholder="Select year"
      />
    </Stack>
  );
}

export default DatePickerModes;
```

### Time, presets, and disabled dates
```tsx preview
import { DatePicker, Stack } from '@rockshin/tao-ui';
import dayjs, { type Dayjs } from 'dayjs';
import { useState } from 'react';

function AdvancedDatePicker() {
  const [dateTime, setDateTime] = useState<Dayjs | null>(null);
  const [preset, setPreset] = useState<Dayjs | null>(null);
  const [future, setFuture] = useState<Dayjs | null>(null);

  return (
    <Stack gap="md" style={{ maxWidth: 320 }}>
      <DatePicker
        value={dateTime}
        onChange={setDateTime}
        showTime
        placeholder="Select date and time"
      />
      <DatePicker
        value={preset}
        onChange={setPreset}
        presets={[
          { label: 'Today', value: dayjs() },
          { label: 'Tomorrow', value: dayjs().add(1, 'day') },
        ]}
      />
      <DatePicker
        value={future}
        onChange={setFuture}
        disabledDate={(current) => current.isBefore(dayjs().startOf('day'))}
        placeholder="Future dates only"
      />
    </Stack>
  );
}

export default AdvancedDatePicker;
```

### Date and time
`showTime` combines date and time selection; format the displayed parts accordingly.
```tsx preview
import { DatePicker, FormField, Stack } from '@rockshin/tao-ui';

import type { Dayjs } from 'dayjs';

import dayjs from 'dayjs';

import { useState } from 'react';

export default function DatePickerWithTime() {
  function Demo() {
    const [val, setVal] = useState<Dayjs | null>(dayjs());
    return (
      <Stack gap="md" style={{ maxWidth: 300 }}>
        <FormField label="Date & Time">
          <DatePicker value={val} onChange={(d) => setVal(d)} showTime />
        </FormField>
        <p style={{ fontSize: 13, color: 'var(--tao-color-text-secondary)' }}>
          Value: {val ? val.format('YYYY-MM-DD HH:mm:ss') : 'none'}
        </p>
      </Stack>
    );
  }
  return <Demo />;
}
```

### Date presets
Offer common dates through `presets` to reduce repeated calendar navigation.
```tsx preview
import { DatePicker, FormField, Stack } from '@rockshin/tao-ui';

import type { Dayjs } from 'dayjs';

import dayjs from 'dayjs';

import { useState } from 'react';

export default function DatePickerWithPresets() {
  function Demo() {
    const [val, setVal] = useState<Dayjs | null>(null);
    return (
      <Stack gap="md" style={{ maxWidth: 300 }}>
        <FormField label="With Presets">
          <DatePicker
            value={val}
            onChange={(d) => setVal(d)}
            presets={[
              { label: 'Today', value: dayjs() },
              { label: 'Yesterday', value: dayjs().subtract(1, 'day') },
              { label: 'Last week', value: dayjs().subtract(7, 'day') },
              { label: 'Last month', value: dayjs().subtract(1, 'month') },
            ]}
          />
        </FormField>
      </Stack>
    );
  }
  return <Demo />;
}
```

### Disable unavailable dates
Use `disabledDate` for business constraints. This example calculates dates locally.
```tsx preview
import { DatePicker, FormField, Stack } from '@rockshin/tao-ui';

import type { Dayjs } from 'dayjs';

import dayjs from 'dayjs';

import { useState } from 'react';

export default function DatePickerDisabledDates() {
  function Demo() {
    const [val, setVal] = useState<Dayjs | null>(null);
    return (
      <Stack gap="md" style={{ maxWidth: 300 }}>
        <FormField label="Only future dates">
          <DatePicker
            value={val}
            onChange={(d) => setVal(d)}
            disabledDate={(d) => d.isBefore(dayjs(), 'day')}
          />
        </FormField>
        <FormField label="With min/max">
          <DatePicker
            value={val}
            onChange={(d) => setVal(d)}
            minDate={dayjs().subtract(7, 'day')}
            maxDate={dayjs().add(30, 'day')}
          />
        </FormField>
      </Stack>
    );
  }
  return <Demo />;
}
```

### Sizes and variants
Choose size and variant to match neighboring input controls.
```tsx preview
import { DatePicker, Stack } from '@rockshin/tao-ui';
export default function Example() {
  return (
    <Stack direction="vertical">
      {(['small', 'medium', 'large'] as const).map((size) => (
        <DatePicker key={size} size={size} />
      ))}
      <DatePicker variant="filled" />
      <DatePicker variant="borderless" />
    </Stack>
  );
}
```

### Status and disabled state
Use error and warning for validation feedback and disabled for unavailable input.
```tsx preview
import { DatePicker, Stack } from '@rockshin/tao-ui';
export default function Example() {
  return (
    <Stack direction="vertical">
      <DatePicker status="error" />
      <DatePicker status="warning" />
      <DatePicker disabled />
    </Stack>
  );
}
```

### Locale switching
TaoProvider locale updates built-in actions, placeholders, and calendar labels.
```tsx preview
import { useState } from 'react';
import {
  DatePicker,
  TaoProvider,
  zhCN,
  enUS,
  Button,
  Stack,
} from '@rockshin/tao-ui';
export default function Example() {
  const [chinese, setChinese] = useState(false);
  return (
    <Stack direction="vertical">
      <Button onClick={() => setChinese(!chinese)}>
        {chinese ? 'Switch to English' : '切换到中文'}
      </Button>
      <TaoProvider locale={chinese ? zhCN : enUS}>
        <DatePicker />
      </TaoProvider>
    </Stack>
  );
}
```

### Date boundaries
minDate and maxDate constrain input and navigation; this example uses a fixed 2026 range.
```tsx preview
import dayjs from 'dayjs';
import { DatePicker } from '@rockshin/tao-ui';
export default function Example() {
  return (
    <DatePicker
      minDate={dayjs('2026-01-01')}
      maxDate={dayjs('2026-12-31')}
      defaultValue={dayjs('2026-06-10')}
    />
  );
}
```

### Controlled value and clearing
Store changes in application state and represent a cleared picker with null.
```tsx preview
import { useState } from 'react';
import type { Dayjs } from 'dayjs';
import { DatePicker, Button, Stack } from '@rockshin/tao-ui';
export default function Example() {
  const [value, setValue] = useState<Dayjs | null>(null);
  return (
    <Stack direction="vertical">
      <DatePicker value={value} onChange={setValue} allowClear />
      <Button onClick={() => setValue(null)}>Clear value</Button>
      <output>{value?.format('YYYY-MM-DD') || 'No selection'}</output>
    </Stack>
  );
}
```

### Display format
format changes display text while values remain Dayjs objects.
```tsx preview
import { DatePicker } from '@rockshin/tao-ui';
export default function Example() {
  return <DatePicker format="DD/MM/YYYY" />;
}
```

### Mobile date drawer
Use `mobile` to try the drawer on desktop and confirm the selected date.
```tsx preview="iframe-follow"
import { DatePicker, FormField, Stack } from '@rockshin/tao-ui';

import type { Dayjs } from 'dayjs';

import dayjs from 'dayjs';

import { useState } from 'react';

export default function DatePickerMobileDatePicker() {
  function Demo() {
    const [val, setVal] = useState<Dayjs | null>(null);
    return (
      <Stack gap="md" style={{ maxWidth: 300 }}>
        <p style={{ color: 'var(--tao-color-text-secondary)', fontSize: 13 }}>
          Using <code>mobile</code> prop to force Drawer mode.
        </p>
        <FormField label="Mobile DatePicker">
          <DatePicker
            value={val}
            onChange={(d) => setVal(d)}
            mobile
            presets={[
              { label: 'Today', value: dayjs() },
              { label: 'Yesterday', value: dayjs().subtract(1, 'day') },
            ]}
          />
        </FormField>
      </Stack>
    );
  }
  return <Demo />;
}
```

Mobile drawer titles use `mobileTitle`, then the nearest `Form.Item` / `FormField` label, then localized default text. Required marks and help text are excluded; placeholders only describe the input. For standalone controls or native HTML labels, pass `mobileTitle="Departure date"` explicitly.
### Mobile selection
Open the picker in phone mode to try selection, confirmation, and clearing inside a drawer.
```tsx preview="iframe-follow"
import { DatePicker, TaoProvider, zhCN } from '@rockshin/tao-ui';
export default function Example() {
  return (
    <TaoProvider locale={zhCN}>
      <DatePicker allowClear />
    </TaoProvider>
  );
}
```

## API


### [#](#datepicker)DatePicker



| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| disabled | Whether to disable | `boolean | undefined` | `-` |
| mobileTitle | Mobile drawer title. Defaults to the Form.Item/FormField label, then locale text. | `ReactNode` | `-` |
| className | Additional css class | `string | undefined` | `-` |
| style | Additional style | `CSSProperties | undefined` | `-` |

