> 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.

# RangePicker

Data Entry`@rockshin/tao-ui`

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

Lets users select a start and end date as one range value.

## When to use

Use RangePicker for reporting windows, booking windows, and filters with start/end dates.

**Recommended**

- Use presets for common ranges such as today, this week, or last 30 days.
- Make inclusive/exclusive range behavior clear when it matters.

**Avoid**

- Do not use the component outside its intended interaction model.

## Examples


### Basic usage
```tsx preview
import { FormField, RangePicker } from '@rockshin/tao-ui';

function RangePickerExample() {
  return (
    <FormField label="Reporting period">
      <RangePicker />
    </FormField>
  );
}

export default RangePickerExample;
```

### Controlled range
```tsx preview
import { RangePicker } from '@rockshin/tao-ui';
import dayjs, { type Dayjs } from 'dayjs';
import { useState } from 'react';

function ControlledRangePicker() {
  const [value, setValue] = useState<[Dayjs | null, Dayjs | null] | null>([
    dayjs().startOf('week'),
    dayjs().endOf('week'),
  ]);

  return <RangePicker value={value} onChange={setValue} />;
}

export default ControlledRangePicker;
```

### Presets and time
```tsx preview
import { RangePicker, Stack } from '@rockshin/tao-ui';
import dayjs from 'dayjs';

function RangePickerPresets() {
  return (
    <Stack gap="md">
      <RangePicker
        presets={[
          {
            label: 'This week',
            value: [dayjs().startOf('week'), dayjs().endOf('week')],
          },
          {
            label: 'This month',
            value: [dayjs().startOf('month'), dayjs().endOf('month')],
          },
        ]}
      />
      <RangePicker showTime />
    </Stack>
  );
}

export default RangePickerPresets;
```

### Range selection and clearing
Choose the start and end dates in sequence, maintain the range value, and allow clearing.
```tsx preview
import { FormField, RangePicker, Stack } from '@rockshin/tao-ui';

import type { Dayjs } from 'dayjs';

import { useState } from 'react';

export default function DatePickerRangePickerBasic() {
  function Demo() {
    const [val, setVal] = useState<[Dayjs | null, Dayjs | null] | null>(null);
    return (
      <Stack gap="md" style={{ maxWidth: 500 }}>
        <FormField label="Date Range">
          <RangePicker value={val} onChange={(d) => setVal(d)} />
        </FormField>
        <p style={{ fontSize: 13, color: 'var(--tao-color-text-secondary)' }}>
          Range: {val?.[0]?.format('YYYY-MM-DD') ?? '?'} ~{' '}
          {val?.[1]?.format('YYYY-MM-DD') ?? '?'}
        </p>
      </Stack>
    );
  }
  return <Demo />;
}
```

### Range presets
Offer common report ranges using the same value structure as manual selections.
```tsx preview
import { FormField, RangePicker, Stack } from '@rockshin/tao-ui';

import type { Dayjs } from 'dayjs';

import dayjs from 'dayjs';

import { useState } from 'react';

export default function DatePickerRangePickerPresets() {
  function Demo() {
    const [val, setVal] = useState<[Dayjs | null, Dayjs | null] | null>(null);
    return (
      <Stack gap="md" style={{ maxWidth: 500 }}>
        <FormField label="Range with presets">
          <RangePicker
            value={val}
            onChange={(d) => setVal(d)}
            presets={[
              {
                label: 'This week',
                value: [dayjs().startOf('week'), dayjs().endOf('week')],
              },
              {
                label: 'This month',
                value: [dayjs().startOf('month'), dayjs().endOf('month')],
              },
              {
                label: 'Last 7 days',
                value: [dayjs().subtract(7, 'day'), dayjs()],
              },
              {
                label: 'Last 30 days',
                value: [dayjs().subtract(30, 'day'), dayjs()],
              },
            ]}
          />
        </FormField>
      </Stack>
    );
  }
  return <Demo />;
}
```

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

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

### Locale switching
TaoProvider locale updates built-in actions, placeholders, and calendar labels.
```tsx preview
import { useState } from 'react';
import {
  RangePicker,
  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}>
        <RangePicker />
      </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 { RangePicker } from '@rockshin/tao-ui';
export default function Example() {
  return (
    <RangePicker
      minDate={dayjs('2026-01-01')}
      maxDate={dayjs('2026-12-31')}
      defaultValue={[dayjs('2026-06-10'), dayjs('2026-06-15')]}
    />
  );
}
```

### Controlled value and clearing
Pass `value` to control the range and save the value received by `onChange`. Set `value` to `null` to reset the range from your application.
With both endpoints enabled, the built-in clear control reports `onChange(null, ['', ''])`. Since [0.0.49](https://rickyshin93.github.io/tao-ui/guide/changelog.md), RangePicker also discards any text still being edited without first emitting it as a selected range.
```tsx preview
import { useState } from 'react';
import type { Dayjs } from 'dayjs';
import { RangePicker, Button, Stack } from '@rockshin/tao-ui';
export default function Example() {
  const [value, setValue] = useState<[Dayjs | null, Dayjs | null] | null>(null);
  return (
    <Stack direction="vertical">
      <RangePicker value={value} onChange={setValue} allowClear />
      <Button onClick={() => setValue(null)}>Clear value</Button>
      <output>
        {value?.map((date) => date?.format('YYYY-MM-DD') || '—').join(' → ') ||
          'No selection'}
      </output>
    </Stack>
  );
}
```

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

### Date and time ranges
showTime adds time selection for both endpoints before confirmation.
```tsx preview
import { RangePicker } from '@rockshin/tao-ui';
export default function Example() {
  return <RangePicker showTime format="YYYY-MM-DD HH:mm" />;
}
```

### Month and year ranges
Use picker to select month or year granularity.
```tsx preview
import { RangePicker, Stack } from '@rockshin/tao-ui';
export default function Example() {
  return (
    <Stack direction="vertical">
      <RangePicker picker="month" />
      <RangePicker picker="year" />
    </Stack>
  );
}
```

### Disable one endpoint
A disabled tuple can lock only the start or end input.
```tsx preview
import { RangePicker } from '@rockshin/tao-ui';
export default function Example() {
  return <RangePicker disabled={[true, false]} />;
}
```

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 { RangePicker, TaoProvider, zhCN } from '@rockshin/tao-ui';
export default function Example() {
  return (
    <TaoProvider locale={zhCN}>
      <RangePicker allowClear />
    </TaoProvider>
  );
}
```

## API


### [#](#rangepicker)RangePicker



| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| disabled | Whether to disable | `boolean | [boolean, 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` | `-` |

