# Time Picker

> Pick a time from a clock face, in 12-hour or 24-hour form.

## Introduction

Add `timepicker` to a text input. `AutoInit()` starts every `.timepicker` except those marked `no-autoinit`.

The clock is inline, not a modal. It is appended to the input’s parent and stays visible. There is no `openByDefault` flag.

 Lunchtime

```
<div class="field">
  <input type="text" class="time-picker" id="lunchtime">
  <label for="lunchtime">Lunchtime</label>
</div>
```

Wrap the input in its own `.field` (or another small parent). The clock is appended inside that parent.

Click a hour on the dial, then a minute. With the default `autoSubmit: true`, finishing the minute writes the input (`HH:MM AM` or `HH:MM PM`). You can also type in the digital hour and minute fields.

## Initialization

The IIFE bundle exposes `Expressive.Timepicker`. Call `init` yourself when you need options other than the defaults, or let `Expressive.AutoInit()` start every `.timepicker`. Unlike Datepicker, the default options already show the clock.

```
document.addEventListener('DOMContentLoaded', function() {
  const elems = document.querySelectorAll('.timepicker');
  const instances = Expressive.Timepicker.init(elems, {
    // specify options here
  });
});
```

Per-instance options can also be passed through AutoInit:

```
Expressive.AutoInit(document.body, {
  Timepicker: { twelveHour: false }
});
```

## Display

The clock is a `.timepicker-container` in the page. There is no overlay and no `autoClose` option.

`container` renders the clock into a specific element instead of the input’s parent. Pass a selector or a DOM node.

### Docked popover

`displayPlugin: 'docked'` wraps the clock in a `.display-docked` popover that appears when the input is clicked or confirmed with Enter, and hides when you click outside.

```
Expressive.Timepicker.init(elem, {
  displayPlugin: 'docked'
});
```

The popover is positioned in document coordinates and then appended to the input’s parent. A `position: relative` parent — including `.field` — shifts that position, so the clock will not sit next to the field. Prefer a static wrapper if you use docked, or keep the clock inline.

Optional `displayPluginOptions`: `margin` (default `5`), `transition` (`10`), `duration` (`250`), and `align` (`'left'`).

## Options

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `duration` | Number | `350` | Transition between the hours and minutes views, in milliseconds. |
| `container` | Element or String | `null` | Element or selector to render the clock into. When omitted, it is appended to the input’s parent. |
| `showClearBtn` | Boolean | `false` | Show a Clear button in the footer. |
| `autoSubmit` | Boolean | `true` | If true, choosing a minute writes the input. If false, Ok and Cancel buttons are added. |
| `defaultTime` | String | `'now'` | Initial time. `'now'` or a `'HH:MM'` string (optionally with `AM`/`PM`). |
| `fromNow` | Number | `0` | Millisecond offset added to `'now'`. |
| `i18n` | Object | See below | Labels for Cancel, Clear, and Ok. |
| `twelveHour` | Boolean | `true` | If true, use a 12-hour clock with AM/PM. If false, use 24-hour hours on two rings. |
| `vibrate` | Boolean | `true` | Vibrate the device when the clock hand changes value. |
| `onSelect` | Function | `null` | Called when a time is chosen on the dial. Receives `(hour, minute)`. |
| `onInputInteraction` | Function | `null` | Called when the input is clicked or confirmed with Enter. |
| `onDone` | Function | `null` | Called when the Ok button is used. Only created when `autoSubmit` is false. |
| `onCancel` | Function | `null` | Called when the Cancel button is used. Only created when `autoSubmit` is false. |
| `displayPlugin` | String | `null` | Set to `'docked'` for a click-to-open popover. |
| `displayPluginOptions` | Object | `null` | Options for the docked plugin: `margin`, `transition`, `duration`, `align`. |

## Internationalization

Pass a partial `i18n` object. Missing keys keep the English defaults.

| Key | Default |
| --- | --- |
| `cancel` | `'Cancel'` |
| `clear` | `'Clear'` |
| `done` | `'Ok'` |

## 12-hour and 24-hour

`twelveHour` defaults to `true`. The intro clock above is 12-hour with AM/PM. Set `twelveHour: false` for a 24-hour dial: hours 1–12 on the inner ring, 13–00 on the outer ring. The written value is then `HH:MM` with no meridian.

 24-hour

```
Expressive.Timepicker.init(document.getElementById('timepicker-24'), {
  twelveHour: false
});
```

## Methods

> All methods are called on the plugin instance. You can get the instance like this:

```
const instance = Expressive.Timepicker.getInstance(elem);
```

### .showView();

Show the hours or minutes face.

**String:** `'hours'` or `'minutes'`.

```
instance.showView('hours');
```

### .done();

Write the current hours and minutes to the input. Pass a truthy argument to clear the input instead.

```
instance.done();
instance.done(true);
```

### .clear();

Clear the input. Same as `done(true)`.

```
instance.clear();
```

### .destroy();

Destroy the plugin instance, remove the clock, and tear down its event handlers.

```
instance.destroy();
```

## Properties

| Name | Type | Description |
| --- | --- | --- |
| `el` | Element | The input the plugin was initialized with. |
| `options` | Object | The options the instance was initialized with. |
| `time` | String | The last value written by `done()`, without the AM/PM suffix. |
| `hours` | Number | The hour currently shown on the clock. |
| `minutes` | Number | The minute currently shown on the clock. |
| `amOrPm` | String | `'AM'` or `'PM'` when `twelveHour` is true. |
| `currentView` | String | `'hours'` or `'minutes'`. |