# Date range picker

Preset ranges such as “Last 30 days”, with a calendar for any other range.

- Component: `<DateRangePicker />`, imported from `em-kit`
- Required props: `onChange`
- HTML page, with live previews: https://emkit.embeddable.com/docs/components/date-range-picker
- Playground (needs a browser): https://emkit.embeddable.com/docs/components/date-range-picker/playground

## Install

```bash
npm install em-kit
pnpm add em-kit   # or, with pnpm
yarn add em-kit   # or, with yarn
bun add em-kit   # or, with bun
```

`react` and `react-dom` 19.1.1 or later are the only peer dependencies; Chart.js installs with the package. Wrap your app, or the part with charts, in `<ChartsProvider>` once: without it every chart throws `EmKit components must be rendered inside <ChartsProvider>.` Every example on this page includes `<ChartsProvider>` so that it runs on its own: if your app already has one, delete it from the example. A control is as wide as its parent and as tall as its title and field, so it needs no height. In the Next.js App Router, every file that renders `ChartsProvider` or a chart starts with `'use client'`, and the provider pins the locale, `theme={{ formatter: { locale: 'en-US' } }}`, so the server and the browser format numbers alike. [The quick start](/docs/quick-start.md#in-the-nextjs-app-router) has the Next.js files.

## Usage

```tsx
import { useState } from 'react';
import { ChartsProvider, DateRangePicker, dateRangePreset } from 'em-kit';
import type { TimeRange } from 'em-kit';

export const Example = () => {
  const [range, setRange] = useState<TimeRange>(
    dateRangePreset('Last 30 days'),
  );
  return (
    <ChartsProvider>
      <div style={{ width: 320 }}>
        <DateRangePicker
          title="Date range"
          selectedValue={range}
          onChange={setRange}
        />
      </div>
    </ChartsProvider>
  );
};
```

- A preset is named by `relativeTimeString`; the picker fills in its `from` and `to` and reports them through `onChange`, in the provider’s time zone.

## Examples

### Two months

The calendar shows two months side by side, for ranges that cross a month.

```tsx
import { useState } from 'react';
import { ChartsProvider, DateRangePicker, dateRangePreset } from 'em-kit';
import type { TimeRange } from 'em-kit';

export const Example = () => {
  const [range, setRange] = useState<TimeRange>(
    dateRangePreset('Last 30 days'),
  );
  return (
    <ChartsProvider>
      <div style={{ width: 320 }}>
        <DateRangePicker
          title="Date range"
          selectedValue={range}
          onChange={setRange}
          showTwoMonths
        />
      </div>
    </ChartsProvider>
  );
};
```

### Calendar only

No preset list: the picker opens straight on the calendar.

```tsx
import { useState } from 'react';
import { ChartsProvider, DateRangePicker } from 'em-kit';
import type { TimeRange } from 'em-kit';

export const Example = () => {
  const [range, setRange] = useState<TimeRange>();
  return (
    <ChartsProvider>
      <div style={{ width: 320 }}>
        <DateRangePicker
          title="Date range"
          selectedValue={range}
          onChange={setRange}
          showCustomRangeOptions={false}
        />
      </div>
    </ChartsProvider>
  );
};
```

## Props

Required props come first. A blank default means the prop is unset unless you pass it.

| Prop | Type | Required | Default | Description |
|---|---|---|---|---|
| `onChange` | `(newDateRange: TimeRange) => void` | yes |  | Called with the range the reader picks: a preset comes with its name and its dates, worked out in the provider’s time zone. A preset passed without dates is reported back with them at once. Called with `undefined` when the reader clears it. |
| `placeholder` | `string` | no | `"Select a date-range"` | Text shown while nothing is chosen. Translates like `title`. |
| `selectedValue` | `TimeRange` | no |  | The chosen range: `{ from: Date, to: Date }`, with an optional `relativeTimeString` naming a preset. `dateRangePreset('Last 30 days')` starts from a preset. |
| `clearable` | `boolean` | no | `true` | Let the reader clear the value. |
| `showCustomRangeOptions` | `boolean` | no | `true` | List the presets, with the calendar behind a “Custom” entry. When `false`, the picker opens straight on the calendar. The presets are the provider’s `theme.defaults.dateRangesOptions`. |
| `showTwoMonths` | `boolean` | no | `false` | Show two months side by side in the calendar. |
| `componentName` | `string` | no |  | A name for this component, included in the interaction events it dispatches on the DOM, for your analytics. |
| `trackingId` | `string` | no |  | An id included in the same events, to tell two instances apart. |
| `title` | `string` | no |  | The title over the field. A `"key\|fallback"` string is looked up in your translations. |
| `description` | `string` | no |  | Smaller text under the title. Translates like `title`. |
| `tooltip` | `string` | no |  | Text for an info icon beside the title. |

```ts
type TimeRange = { from: Date | undefined; to: Date | undefined; relativeTimeString?: string; } | undefined
```

Each is exported from `em-kit` as a type, for example `import type { TimeRange } from 'em-kit'`.

A click payload’s `TimeRange` is `undefined` unless the clicked field is a time dimension, and its `relativeTimeString` is always `undefined`, so read it as `range?.from`. When you pass one, `from` and `to` are enough.

## Field options

Options go in a field’s `inputs`, for example `measure({ name: 'revenue', inputs: { prefix: '$' } })`. Every field takes `prefix`, `suffix`, `decimalPlaces`, `currency`, `abbreviateLargeNumber`, `displayName` and `maxCharacters`. [Field options](/docs/describing-your-data.md#field-options) describes them.
