---
title: "Date Range Field"
description: "Allows users to input a range of dates within a designated field."
canonical_url: "https://vinicunca.dev/akar/components/date-range-field"
---
# Date Range Field

> Allows users to input a range of dates within a designated field.

`````vue [index.vue]
<script setup lang="ts">
import { DateRangeFieldInput, DateRangeFieldRoot, Label } from 'akar'
import './styles.css'
</script>

<template>
  <div class="akar-demo akar-demo-DateRangeField">
    <div class="DateFieldWrapper">
        <Label
          class="DateFieldLabel"
          for="date-field"
        >Input label</Label>

        <DateRangeFieldRoot
          id="date-field"
          v-slot="{ segments }"
          :is-date-unavailable="date => date.day === 19"
          granularity="second"
          class="DateField"
        >
          <template
            v-for="item in segments.start"
            :key="item.part"
          >
            <DateRangeFieldInput
              v-if="item.part === 'literal'"
              :part="item.part"
              class="DateFieldLiteral"
              type="start"
            >
              {{ item.value }}
            </DateRangeFieldInput>
            <DateRangeFieldInput
              v-else
              :part="item.part"
              class="DateFieldSegment"
              type="start"
            >
              {{ item.value }}
            </DateRangeFieldInput>
          </template>
          -
          <template
            v-for="item in segments.end"
            :key="item.part"
          >
            <DateRangeFieldInput
              v-if="item.part === 'literal'"
              :part="item.part"
              class="DateFieldLiteral"
              type="end"
            >
              {{ item.value }}
            </DateRangeFieldInput>
            <DateRangeFieldInput
              v-else
              :part="item.part"
              class="DateFieldSegment"
              type="end"
            >
              {{ item.value }}
            </DateRangeFieldInput>
          </template>
        </DateRangeFieldRoot>
      </div>
  </div>
</template>
```

```css [styles.css]
@import '../_colors/black-alpha.css';
@import '../_colors/mauve.css';
@import '../_colors/grass.css';

@scope (.akar-demo-DateRangeField) {
.DateFieldWrapper {
  display: flex;
  flex-direction: column;
  gap: 0.5rem;
}

.DateFieldLabel {
  font-size: 0.875rem;
  line-height: 1.25rem;
  color: var(--gray-9);
}

.DateField {
  display: flex;
  padding: 0.5rem;
  align-items: center;
  border-radius: 0.25rem;
  border-width: 1px;
  text-align: center;
  background-color: #ffffff;
  user-select: none;
  color: var(--green-10);
  border: 1px solid var(--gray-9);
}

.DateField::placeholder {
  color: var(--mauve-5);
}

.DateField[data-invalid] {
  border: 1px solid var(--red-500);
}

.DateFieldLiteral {
  padding: 0.25rem;
}

.DateFieldSegment {
  padding: 0.25rem;
}

.DateFieldSegment:hover{
  background-color: var(--grass-4);
}

.DateFieldSegment:focus {
  background-color: var(--grass-2);
}

.DateFieldSegment:[aria-valuetext='Empty'] {
  color: var(--grass-6);
}
}
```

## Features

- Full keyboard navigation
- Can be controlled or uncontrolled
- Focus is fully managed
- Localization support
- Highly composable
- Accessible by default
- Supports both date and date-time formats

## Preface

The component depends on the [@internationalized/date](https://react-spectrum.adobe.com/internationalized/date/index.html) package, which solves a lot of the problems that come with working with dates and times in JavaScript.

We highly recommend reading through the documentation for the package to get a solid feel for how it works, and you'll need to install it in your project to use the date-related components.

## Installation

Install the date package.

```bash [pnpm]
pnpm add @internationalized/date
```

```bash [yarn]
yarn add @internationalized/date
```

```bash [npm]
npm install @internationalized/date
```

```bash [bun]
bun add @internationalized/date
```

Install the component from your command line.

```bash [pnpm]
pnpm add akar
```

```bash [yarn]
yarn add akar
```

```bash [npm]
npm install akar
```

```bash [bun]
bun add akar
```

## Anatomy

Import all parts and piece them together.

```vue
<script setup>
import {
  DateRangeFieldInput,
  DateRangeFieldRoot,
} from 'akar';
</script>

<template>
  <DateRangeFieldRoot>
    <DateRangeFieldInput />
  </DateRangeFieldRoot>
</template>
```

## API Reference

### Root

Contains all the parts of a date field

**Props**

| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| `as` | `"div"` | `AsTag \| Component` | The element or component this component should render as. Can be overwritten by `asChild`. |
| `asChild` |  | `boolean` | Change the default rendered element for the one passed as a child, merging their props and behavior.<br><br>Read our [Composition](/akar/guides/composition) guide for more details. |
| `defaultPlaceholder` |  | `DateValue` | The default placeholder date |
| `defaultValue` |  | `DateRange` | The default value for the calendar |
| `dir` |  | `"ltr" \| "rtl"` | The reading direction of the date field when applicable.<br><br>If omitted, inherits globally from `ConfigProvider` or assumes LTR (left-to-right) reading mode. |
| `disabled` | `false` | `boolean` | Whether or not the date field is disabled |
| `granularity` |  | `"day" \| "hour" \| "minute" \| "second"` | The granularity to use for formatting times. Defaults to day if a CalendarDate is provided, otherwise defaults to minute. The field will render segments for each part of the date up to and including the specified granularity |
| `hideTimeZone` |  | `boolean` | Whether or not to hide the time zone segment of the field |
| `hourCycle` |  | `12 \| 24` | The hour cycle used for formatting times. Defaults to the local preference |
| `id` |  | `string` | Id of the element |
| `isDateUnavailable` |  | `Matcher` | A function that returns whether or not a date is unavailable |
| `locale` |  | `string` | The locale to use for formatting dates |
| `maxValue` |  | `DateValue` | The maximum date that can be selected |
| `minValue` |  | `DateValue` | The minimum date that can be selected |
| `modelValue` |  | `DateRange \| null` | The controlled value of the field. Can be bound as `v-model`. |
| `name` |  | `string` | The name of the field. Submitted with its owning form as part of a name/value pair. |
| `placeholder` |  | `DateValue` | The placeholder date, which is used to determine what month to display when no date is selected. This updates as the user navigates the calendar and can be used to programmatically control the calendar view |
| `readonly` | `false` | `boolean` | Whether or not the date field is readonly |
| `required` |  | `boolean` | When `true`, indicates that the user must set the value before the owning form can be submitted. |
| `step` |  | `DateStep` | The stepping interval for the time fields. Defaults to `1`. |

**Events**

| Event | Payload | Description |
| --- | --- | --- |
| `update:modelValue` | `date: DateRange` | Event handler called whenever the model value changes |
| `update:placeholder` | `date: DateValue` | Event handler called whenever the placeholder value changes |

**Slots**

| Slot | Payload | Description |
| --- | --- | --- |
| `modelValue` | `DateRange \| null` | The current date range of the field |
| `segments` | `{ start: { part: SegmentPart; value: string; }[]; end: { part: SegmentPart; value: string; }[]; }` | The date field segment contents |
| `isInvalid` | `boolean` | Value if the input is invalid |

**Methods**

| Method | Type | Description |
| --- | --- | --- |
| `setFocusedElement` | `(el: HTMLElement) => void` |  |

[DateRangeFieldRoot.vue source](https://github.com/vinicunca/akar/blob/v2.0.20/packages/core/src/DateRangeField/DateRangeFieldRoot.vue)

| Data attribute | Value |
| --- | --- |
| `[data-readonly]` | Present when readonly |
| `[data-disabled]` | Present when disabled |
| `[data-invalid]` | Present when invalid |

### Input

Contains the date field segments

**Props**

| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| `as` | `"div"` | `AsTag \| Component` | The element or component this component should render as. Can be overwritten by `asChild`. |
| `asChild` |  | `boolean` | Change the default rendered element for the one passed as a child, merging their props and behavior.<br><br>Read our [Composition](/akar/guides/composition) guide for more details. |
| `part*` |  | `"day" \| "month" \| "year" \| "hour" \| "minute" \| "second" \| "dayPeriod" \| "literal" \| "timeZoneName"` | The part of the date to render |
| `type*` |  | `"start" \| "end"` | The type of field to render (start or end) |

[DateRangeFieldInput.vue source](https://github.com/vinicunca/akar/blob/v2.0.20/packages/core/src/DateRangeField/DateRangeFieldInput.vue)

| Data attribute | Value |
| --- | --- |
| `[data-disabled]` | Present when disabled |
| `[data-invalid]` | Present when invalid |
| `[data-placeholder]` | Present when no value is set |

## Accessibility

### Keyboard Interactions

| Key | Description |
| --- | --- |
| <kbd>Tab</kbd> | When focus moves onto the date field, focuses the first segment. |
| <kbd>ArrowLeft</kbd> / <kbd>ArrowRight</kbd> | Navigates between the date field segments. |
| <kbd>ArrowUp</kbd> / <kbd>ArrowDown</kbd> | Increments/changes the value of the segment. |
| <kbd>0-9</kbd> | When the focus is on a numeric `DateFieldInput`, it types in the number and focuses the next segment if the next input would result in an invalid value. |
| <kbd>Backspace</kbd> | Deletes a digit from the focused numeric segments. |
| <kbd>A</kbd> / <kbd>P</kbd> | When the focus is on the day period, it sets it to AM or PM. |

---

- [GitHub](https://github.com/vinicunca/akar/blob/v2.0.20/packages/core/src/DateRangeField)
- [npm](https://www.npmjs.com/package/akar)


## Sitemap

See the full [sitemap](https://vinicunca.dev/sitemap.md) for all pages.