---
title: "Time Field"
description: "Enables users to input specific times within a designated field."
canonical_url: "https://vinicunca.dev/akar/components/time-field"
---
# Time Field

> Enables users to input specific times within a designated field.

`````vue [index.vue]
<script setup lang="ts">
import { Label, TimeFieldInput, TimeFieldRoot } from 'akar'

import './styles.css'
</script>

<template>
  <div class="akar-demo akar-demo-TimeField">
    <div class="TimeFieldWrapper">
        <Label
          class="TimeFieldLabel"
          for="time-field"
        >Appointment</Label>
        <TimeFieldRoot
          id="time-field"
          v-slot="{ segments }"
          granularity="second"
          class="TimeField"
        >
          <template
            v-for="item in segments"
            :key="item.part"
          >
            <TimeFieldInput
              v-if="item.part === 'literal'"
              :part="item.part"
              class="TimeFieldLiteral"
            >
              {{ item.value }}
            </TimeFieldInput>
            <TimeFieldInput
              v-else
              :part="item.part"
              class="TimeFieldSegment"
            >
              {{ item.value }}
            </TimeFieldInput>
          </template>
        </TimeFieldRoot>
      </div>
  </div>
</template>
```

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

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

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

.TimeField {
    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);
}

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

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

.TimeFieldLiteral {
    padding: 0.25rem;
}

.TimeFieldSegment {
    padding: 0.25rem;
}

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

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

.TimeFieldSegment:[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

## 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 {
  TimeFieldInput,
  TimeFieldRoot,
} from 'akar';
</script>

<template>
  <TimeFieldRoot>
    <TimeFieldInput />
  </TimeFieldRoot>
</template>
```

## API Reference

### Root

Contains all the parts of a time 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` |  | `TimeValue` | The default placeholder date |
| `defaultValue` |  | `TimeValue` | The default value for the calendar |
| `dir` |  | `"ltr" \| "rtl"` | The reading direction of the time 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 time field is disabled |
| `granularity` |  | `"hour" \| "minute" \| "second"` | The granularity to use for formatting times. Defaults to minute if a Time 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 |
| `locale` |  | `string` | The locale to use for formatting dates |
| `maxValue` |  | `TimeValue` | The maximum date that can be selected |
| `minValue` |  | `TimeValue` | The minimum date that can be selected |
| `modelValue` |  | `TimeValue \| null` | The controlled checked state 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` |  | `TimeValue` | The placeholder date, which is used to determine what time to display when no time is selected. This updates as the user navigates the field |
| `readonly` | `false` | `boolean` | Whether or not the time 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`. |
| `stepSnapping` | `false` | `boolean` | Whether to enforce snapping the value to the nearest step increment after input. Defaults to `false`. |

**Events**

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

**Slots**

| Slot | Payload | Description |
| --- | --- | --- |
| `modelValue` | `TimeValue` | The current time of the field |
| `segments` | `{ part: SegmentPart; value: string; }[]` | The time field segment contents |
| `isInvalid` | `boolean` | Value if the input is invalid |

**Methods**

| Method | Type | Description |
| --- | --- | --- |
| `setFocusedElement` | `(el: HTMLElement) => void` | Helper to set the focused element inside the DateField |

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

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

### Input

Contains the time 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 |

[TimeFieldInput.vue source](https://github.com/vinicunca/akar/blob/v2.0.20/packages/core/src/TimeField/TimeFieldInput.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 time field, focuses the first segment. |
| <kbd>ArrowLeft</kbd> / <kbd>ArrowRight</kbd> | Navigates between the time 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 `TimeFieldInput`, 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/TimeField)
- [npm](https://www.npmjs.com/package/akar)


## Sitemap

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