Timepicker UI

https://timepicker-ui.vercel.app/docs
Admin
Timepicker UI provides a framework-agnostic, accessible, and themeable JavaScript component for...
Tokens:51,853
Snippets:539
Trust Score:7.8
Update:1 month ago
Show doc for...
Tokens:
Raw
### Migration Examples

Source: https://timepicker-ui.vercel.app/docs/changelog

Code examples from the changelog showing CSS class renames, new options structure, and migration steps.

```diff
// CSS Class Names (ALL Classes changed)
- .timepicker-ui-*
+ .tp-ui-*

Examples:
- .timepicker-ui-wrapper       -> .tp-ui-wrapper
- .timepicker-ui-modal         -> .tp-ui-modal
```

```javascript
// v4.0.0 (grouped - NEW):
+{
+  clock: {
+    type: '24h'
+  }
+}
```

```text
// Migration Steps:
1. Find & replace all CSS class names in your stylesheets
2. Find & replace all CSS variable names in your custom themes
3. Reorganize options into groups: clock, ui, labels, behavior, callbacks
4. Update clockType -> clock.type, theme -> ui.theme, onConfirm -> callbacks.onConfirm
5. Test all customizations and themes thoroughly
```

--------------------------------

### Glassmorphic Theme Example

Source: https://timepicker-ui.vercel.app/docs/features/themes

Example of initializing Timepicker UI with the Glassmorphic theme, enabling backdrop and animation.

```typescript
import 'timepicker-ui/main.css';
import 'timepicker-ui/theme-glassmorphic.css';

const picker = new TimepickerUI(input, {
  ui: {
    theme: 'glassmorphic',
    backdrop: true,
    animation: true
  }
});
```

--------------------------------

### Cyberpunk Theme Example

Source: https://timepicker-ui.vercel.app/docs/features/themes

Example of initializing Timepicker UI with the Cyberpunk theme, enabling animation and backdrop.

```typescript
import 'timepicker-ui/main.css';
import 'timepicker-ui/theme-cyberpunk.css';

const picker = new TimepickerUI(input, {
  ui: {
    theme: 'cyberpunk',
    animation: true,
    backdrop: true
  },
  clock: {
    type: '24h'
  }
});
```

--------------------------------

### Blueprint Theme Example

Source: https://timepicker-ui.vercel.app/docs/features/themes

Example of initializing Timepicker UI with the Blueprint theme. The dark sibling `blueprint-dark` can be imported and used similarly.

```typescript
import 'timepicker-ui/main.css';
import 'timepicker-ui/theme-blueprint.css';

const picker = new TimepickerUI(input, {
  ui: {
    theme: 'blueprint',
    animation: true
  }
});

// Dark sibling
// import 'timepicker-ui/theme-blueprint-dark.css';
// ui: { theme: 'blueprint-dark' }
```

--------------------------------

### Install Timepicker-UI with npm, yarn, or pnpm

Source: https://timepicker-ui.vercel.app/docs/installation

Choose your preferred package manager to install the Timepicker-UI library.

```bash
npm install timepicker-ui
```

```bash
yarn add timepicker-ui
```

```bash
pnpm add timepicker-ui
```

--------------------------------

### Material Design 3 Theme Example

Source: https://timepicker-ui.vercel.app/docs/features/themes

Example of initializing Timepicker UI with the Material Design 3 green theme.

```typescript
import 'timepicker-ui/main.css';
import 'timepicker-ui/theme-m3-green.css';

const picker = new TimepickerUI(input, {
  ui: {
    theme: 'm3-green',
    animation: true
  },
  clock: {
    type: '12h'
  }
});
```

--------------------------------

### Keyboard Navigation

Source: https://timepicker-ui.vercel.app/docs/advanced/accessibility

Keyboard navigation example showing how to create a TimepickerUI instance and handle keyboard shortcuts.

```typescript
const picker = new TimepickerUI(input, {
  // Keyboard navigation is enabled by default
  // All interactive elements are focusable
});

picker.create();

// Arrow keys work on both inputs and clock face
// - On hour/minute inputs: Up/Down adjusts by ±1
// - On clock face numbers: Up/Down/Left/Right adjusts by ±1
// - Disabled times are automatically skipped

// A/P shortcuts work from anywhere except inputs
document.addEventListener('keydown', (e) => {
  if (e.key === 'a' || e.key === 'A') {
    // Switches to AM (when not typing in input)
  }
});
```

--------------------------------

### Install Timepicker UI with TypeScript

Source: https://timepicker-ui.vercel.app/docs/api/typescript

Install the package using npm. TypeScript definitions are included automatically, making types available for import.

```bash
npm install timepicker-ui
```

```typescript
// Types are automatically available
import { TimepickerUI } from 'timepicker-ui';
import type { TimepickerOptions, ConfirmEventData } from 'timepicker-ui';
```

--------------------------------

### Basic Mobile Setup for Timepicker-UI

Source: https://timepicker-ui.vercel.app/docs/features/mobile

Enable mobile optimizations, smooth animations, and a full backdrop on small screens when initializing Timepicker-UI.

```typescript
const picker = new TimepickerUI(input, {
  ui: {
    mobile: true,       // Enable mobile optimizations
    animation: true,    // Smooth animations
    backdrop: true      // Full backdrop on small screens
  }
});

picker.create();

```

--------------------------------

### Portuguese Locale Configuration

Source: https://timepicker-ui.vercel.app/docs/advanced/localization

Example configuration for Portuguese locale using a 24-hour format with custom 'Confirmar' and 'Cancelar' labels.

```typescript
const picker = new TimepickerUI(input, {
  clock: { type: '24h' },
  labels: {
    ok: 'Confirmar',
    cancel: 'Cancelar'
  }
});
```

--------------------------------

### Italian Locale Configuration

Source: https://timepicker-ui.vercel.app/docs/advanced/localization

Example configuration for Italian locale using a 24-hour format with custom 'OK' and 'Annulla' labels.

```typescript
const picker = new TimepickerUI(input, {
  clock: { type: '24h' },
  labels: {
    ok: 'OK',
    cancel: 'Annulla'
  }
});
```

--------------------------------

### Spanish Localization Example

Source: https://timepicker-ui.vercel.app/docs/advanced/localization

Example of how to set Spanish labels directly when initializing Timepicker UI. Ensure the 'input' element is defined in your HTML.

```typescript
1const picker = new TimepickerUI(input, {
2  labels: {
3    ok: 'Aceptar',
4    cancel: 'Cancelar',
5    am: 'AM',
6    pm: 'PM'
7  }
8});
9
10picker.create();
```

--------------------------------

### French Localization Example

Source: https://timepicker-ui.vercel.app/docs/advanced/localization

Example of how to set French labels directly when initializing Timepicker UI. Ensure the 'input' element is defined in your HTML.

```typescript
1const picker = new TimepickerUI(input, {
2  labels: {
3    ok: 'Valider',
4    cancel: 'Annuler',
5    am: 'AM',
6    pm: 'PM'
7  }
8});
9
10picker.create();
```

--------------------------------

### German Localization Example

Source: https://timepicker-ui.vercel.app/docs/advanced/localization

Example of how to set German labels directly when initializing Timepicker UI. Ensure the 'input' element is defined in your HTML.

```typescript
1const picker = new TimepickerUI(input, {
2  labels: {
3    ok: 'OK',
4    cancel: 'Abbrechen',
5    am: 'AM',
6    pm: 'PM'
7  }
8});
9
10picker.create();
```

--------------------------------

### Timepicker UI v3.x Initialization

Source: https://timepicker-ui.vercel.app/docs/whats-new

Example of initializing Timepicker UI with options in version 3.x. This shows the older, flat structure for configuration.

```typescript
const picker = new TimepickerUI(input, {
  clockType: '12h',
  theme: 'dark',
  mobile: true,
  animation: true,
  incrementMinutes: 5,
  okLabel: 'Confirm',
  cancelLabel: 'Close'
});
```

--------------------------------

### Complete Timepicker Validation Example

Source: https://timepicker-ui.vercel.app/docs/features/validation

Integrates HTML structure, CSS for styling, and JavaScript for client-side validation logic. This example demonstrates how to provide immediate feedback on time input validity.

```html
<div class="form-group">
  <label for="timepicker">Select time</label>
  <input 
    type="time" 
    id="timepicker"
    class="form-control"
    required
  />
  <span class="error-message" id="error"></span>
</div>

<style>
.form-control {
  border: 2px solid #e5e7eb;
  border-radius: 0.5rem;
  padding: 0.5rem 0.75rem;
  transition: all 0.2s;
}

.form-control.error {
  border-color: #ef4444;
}

.form-control.success {
  border-color: #10b981;
}
</style>

<script>
const input = document.querySelector('#timepicker');
const errorMsg = document.querySelector('#error');

input.addEventListener('change', () => {
  if (input.validity.valid) {
    input.classList.remove('error');
    input.classList.add('success');
    errorMsg.textContent = '';
  } else {
    input.classList.add('error');
    input.classList.remove('success');
    errorMsg.textContent = input.validationMessage;
  }
});
</script>
```

--------------------------------

### Japanese Locale Configuration

Source: https://timepicker-ui.vercel.app/docs/advanced/localization

Example configuration for Japanese locale using a 24-hour format with custom 'OK' and 'Cancel' labels.

```typescript
const picker = new TimepickerUI(input, {
  clock: { type: '24h' },
  labels: {
    ok: '確認',
    cancel: 'キャンセル'
  }
});
```

--------------------------------

### Basic Timepicker Setup (v4.0.0)

Source: https://timepicker-ui.vercel.app/docs/migration-guide

Initializes a Timepicker UI instance with a 12-hour clock. Ensure the target element '#input' exists in your HTML.

```typescript
1// v4.0.0
2const timepicker = new TimepickerUI('#input', {
3  clock: { type: '12h' },
});
```

--------------------------------

### Arabic Locale Configuration

Source: https://timepicker-ui.vercel.app/docs/advanced/localization

Example configuration for Arabic locale using a 12-hour format with custom labels for OK, Cancel, AM, and PM.

```typescript
const picker = new TimepickerUI(input, {
  clock: { type: '12h' },
  labels: {
    ok: 'موافق',
    cancel: 'إلغاء',
    am: 'ص',
    pm: 'م'
  }
});
```

--------------------------------

### v3.x Flat API Structure

Source: https://timepicker-ui.vercel.app/docs/migration-guide

Example of the old flat API structure used in v3.x. This configuration will not work with v4.0.0.

```typescript
const timepicker = new TimepickerUI('#input', {
  clockType: '12h',
  amLabel: 'AM',
  pmLabel: 'PM',
  okLabel: 'OK',
  cancelLabel: 'Cancel',
  timeLabel: 'Select time',
  animation: true,
  backdrop: true,
  theme: 'basic',
  incrementHours: 1,
  incrementMinutes: 5,
  focusTrap: true,
  delayHandler: 300,
  mobile: false,
  editable: false,
  onOpen: (event) => console.log('opened', event),
  onConfirm: (event) => console.log('confirmed', event),
});
```

--------------------------------

### Descriptive Label

Source: https://timepicker-ui.vercel.app/docs/advanced/accessibility

Example of a descriptive label with required indicator and hint.

```html
<label for="meeting-time" class="form-label">
  Meeting Time
  <span class="text-muted">(Required)</span>
</label>
<input 
  type="time" 
  id="meeting-time"
  required
  aria-required="true"
  aria-describedby="meeting-time-hint"
/>
<div id="meeting-time-hint" class="form-hint">
  Select a time between 9:00 AM and 5:00 PM
</div>
```

--------------------------------

### Live Region

Source: https://timepicker-ui.vercel.app/docs/advanced/accessibility

Example of a live region for screen reader announcements.

```html
<!-- Live region for screen reader announcements -->
<div 
  class="timepicker-announcer" 
  role="status" 
  aria-live="polite" 
  aria-atomic="true"
  style="position: absolute; width: 1px; height: 1px; 
         overflow: hidden; clip: rect(0,0,0,0);"
>
  <!-- Dynamically updated by the timepicker -->
  <!-- Announces: "Hour changed to 14", "Minute changed to 30", etc. -->
</div>

<script>
// Timepicker automatically announces changes via live region
// No manual setup required - works out of the box

// Example announcements:
// - "Hour changed to 14"
// - "Minute changed to 30" 
// - "AM selected"
// - "PM selected"

// Live region updates happen on:
// - Clock hand drag
// - Clock number click
// - Arrow key navigation
// - AM/PM toggle
</script>
```

--------------------------------

### Russian Locale Configuration

Source: https://timepicker-ui.vercel.app/docs/advanced/localization

Example configuration for Russian locale using a 24-hour format with custom 'OK' and 'Cancel' labels.

```typescript
const picker = new TimepickerUI(input, {
  clock: { type: '24h' },
  labels: {
    ok: 'ОК',
    cancel: 'Отмена'
  }
});
```

--------------------------------

### Create, Get, and Destroy Timepicker Instances

Source: https://timepicker-ui.vercel.app/docs/legacy-migration

Demonstrates how to create multiple Timepicker UI instances with unique IDs, retrieve an instance by its ID, and destroy all instances simultaneously using static methods.

```javascript
const picker1 = new TimepickerUI('#input1', { id: 'picker1' });
const picker2 = new TimepickerUI('#input2', { id: 'picker2' });

const instance = TimepickerUI.getById('picker1');

TimepickerUI.destroyAll();
```

--------------------------------

### Chinese Simplified Locale Configuration

Source: https://timepicker-ui.vercel.app/docs/advanced/localization

Example configuration for Simplified Chinese locale using a 24-hour format with custom 'OK' and 'Cancel' labels.

```typescript
const picker = new TimepickerUI(input, {
  clock: { type: '24h' },
  labels: {
    ok: '确定',
    cancel: '取消'
  }
});
```

--------------------------------

### Register Multiple Plugins for Timepicker UI

Source: https://timepicker-ui.vercel.app/docs/features/plugins

Register all required plugins once at application startup before creating TimepickerUI instances. This example shows registering Range, Timezone, and Wheel plugins.

```javascript
import { TimepickerUI, PluginRegistry } from 'timepicker-ui';
import { RangePlugin } from 'timepicker-ui/plugins/range';
import { TimezonePlugin } from 'timepicker-ui/plugins/timezone';
import { WheelPlugin } from 'timepicker-ui/plugins/wheel';
import 'timepicker-ui/main.css';

// Register plugins once at startup
PluginRegistry.register(RangePlugin);
PluginRegistry.register(TimezonePlugin);
PluginRegistry.register(WheelPlugin);

// Range + Timezone picker
const rangePicker = new TimepickerUI(input1, {
  range: { enabled: true },
  timezone: { enabled: true }
});
rangePicker.create();

// Wheel picker
const wheelPicker = new TimepickerUI(input2, {
  ui: { mode: 'wheel' }
});
wheelPicker.create();

```

--------------------------------

### Advanced Timepicker Setup (v4.0.0)

Source: https://timepicker-ui.vercel.app/docs/migration-guide

Configures Timepicker UI with a 24-hour clock, custom minute increments, disabled times, theme, UI animations, and behavior options. Callbacks for open, confirm, and cancel events are included.

```typescript
1// v4.0.0
2const timepicker = new TimepickerUI('#input', {
3  clock: {
4    type: '24h',
5    incrementMinutes: 15,
6    disabledTime: {
7      hours: [0, 1, 2, 23],
8      interval: ['00:00 - 06:00', '22:00 - 23:59'],
9    },
10  },
11  ui: {
12    theme: 'm3-green',
13    animation: true,
14    backdrop: true,
15    mobile: false,
16    editable: true,
17  },
18  labels: {
19    time: 'Pick a time',
20    ok: 'Confirm',
21    cancel: 'Dismiss',
22  },
23  behavior: {
24    focusTrap: true,
25    delayHandler: 300,
26    focusInputAfterClose: true,
27  },
28  callbacks: {
29    onOpen: () => console.log('Opened'),
30    onConfirm: (data) => console.log('Time selected:', data),
31    onCancel: () => console.log('Cancelled'),
32  },
33});
```

--------------------------------

### Migrate Timepicker UI Options from v3.x to v4.0.0

Source: https://timepicker-ui.vercel.app/docs/whats-new

Compares the old options structure of Timepicker UI v3.x with the new structure in v4.0.0. Use this example to understand how to update your configuration when migrating.

```typescript
1// v3.x
2const picker = new TimepickerUI(input, {
  clockType: '24h',
  theme: 'dark',
  mobile: true,
  animation: true,
  incrementMinutes: 15,
  okLabel: 'Confirm',
  cancelLabel: 'Close',
  focusTrap: true
});
12
13// v4.0.0
14const picker = new TimepickerUI(input, {
15  clock: {
16    type: '24h',
17    incrementMinutes: 15
18  },
19  ui: {
20    theme: 'dark',
21    mobile: true,
22    animation: true
23  },
24  labels: {
25    ok: 'Confirm',
26    cancel: 'Close'
27  },
28  behavior: {
29    focusTrap: true
30  }
31});
```

--------------------------------

### Subscribe to 'open' event once

Source: https://timepicker-ui.vercel.app/docs/api/events

Use the `once` method to subscribe to an event that will only fire the first time it occurs. This is useful for one-time setup or logging.

```typescript
picker.once('open', () => {
  console.log('Opened for the first time');
});
```

--------------------------------

### Custom ARIA Label on Input

Source: https://timepicker-ui.vercel.app/docs/advanced/accessibility

Example of adding custom aria-label and aria-describedby to an input element.

```html
<input
  type="time"
  id="timepicker"
  aria-label="Select appointment time"
  aria-describedby="time-help"
/>
<span id="time-help" class="sr-only">
  Use arrow keys to select time. Press Enter to confirm.
</span>
```

--------------------------------

### v4.0.0 Grouped API Structure

Source: https://timepicker-ui.vercel.app/docs/migration-guide

Example of the new grouped API structure in v4.0.0. All v3.x configurations must be updated to this format.

```typescript
const timepicker = new TimepickerUI('#input', {
  clock: {
    type: '12h',
    incrementHours: 1,
    incrementMinutes: 5,
  },
  ui: {
    animation: true,
    backdrop: true,
    theme: 'basic',
    mobile: false,
    editable: false,
  },
  labels: {
    am: 'AM',
    pm: 'PM',
    ok: 'OK',
    cancel: 'Cancel',
    time: 'Select time',
  },
  behavior: {
    focusTrap: true,
    delayHandler: 300,
  },
  callbacks: {
    onOpen: (event) => console.log('opened', event),
    onConfirm: (event) => console.log('confirmed', event),
  },
});
```

--------------------------------

### Timepicker UI v4.0.0 Initialization with Grouped Options

Source: https://timepicker-ui.vercel.app/docs/whats-new

Example of initializing Timepicker UI with the new grouped options architecture in version 4.0.0. Options are now organized into 'clock', 'ui', and 'labels' for better maintainability.

```typescript
const picker = new TimepickerUI(input, {
  clock: {
    type: '12h',
    incrementMinutes: 5
  },
  ui: {
    theme: 'dark',
    mobile: true,
    animation: true
  },
  labels: {
    ok: 'Confirm',
    cancel: 'Close'
  }
});
```

--------------------------------

### Inline Mode Timepicker Setup (v4.0.0)

Source: https://timepicker-ui.vercel.app/docs/migration-guide

Sets up Timepicker UI in inline mode, specifying a container and disabling focus trap. Ensure the 'timepicker-container' ID exists in your HTML.

```typescript
1// v4.0.0
2const timepicker = new TimepickerUI('#input', {
3  ui: {
4    inline: {
5      enabled: true,
6      containerId: 'timepicker-container',
7      showButtons: false,
8      autoUpdate: true,
9    },
10  },
11  behavior: {
12    focusTrap: false, // Automatically set if not specified
13  },
14});
```

--------------------------------

### Customize Timepicker-UI with Options

Source: https://timepicker-ui.vercel.app/docs/quick-start

Configure Timepicker-UI with custom options for UI theme, clock type, and confirmation callbacks. This example uses a dark theme and 24-hour clock format.

```typescript
const picker = new TimepickerUI(input, {
  ui: {
    theme: 'dark',
    animation: true,
    backdrop: true
  },
  clock: {
    type: '24h'
  },
  callbacks: {
    onConfirm: (data) => {
      console.log('Selected time:', data);
    }
  }
});
picker.create();

```

--------------------------------

### wheel:scroll:start Event

Source: https://timepicker-ui.vercel.app/docs/api/events

Triggered when a wheel column starts scrolling in wheel mode.

```APIDOC
## `wheel:scroll:start` Event

### Description
Triggered when a wheel column starts scrolling (wheel mode only).

### Event Name
`wheel:scroll:start`

### Data Payload
- **column** (string) - The column that started scrolling ('hours', 'minutes', or 'ampm').

### Example
```javascript
picker.on('wheel:scroll:start', (data) => {
  console.log('Scroll started on column:', data.column);
});
```
```

--------------------------------

### Complete Timepicker UI Initialization

Source: https://timepicker-ui.vercel.app/docs/api/options

Demonstrates the full initialization of Timepicker UI with all available options configured for clock, UI, wheel, labels, behavior, and callbacks. Use this as a reference for comprehensive customization.

```typescript
const picker = new TimepickerUI(input, {
  // Clock options
  clock: {
    type: '24h',
    incrementHours: 1,
    incrementMinutes: 5,
    autoSwitchToMinutes: true,
    disabledTime: {
      hours: [0, 1, 2, 3],
      interval: '10:00 - 12:00'
    },
    currentTime: {
      updateInput: true,
      time: new Date()
    }
  },
  
  // UI options
  ui: {
    theme: 'dark',
    animation: true,
    backdrop: true,
    mobile: false,
    enableScrollbar: false,
    enableSwitchIcon: false,
    editable: false,
    cssClass: 'custom-picker',
    appendModalSelector: '#timepicker-container'
  },
  
  // Wheel options
  wheel: {
    placement: 'bottom',
    hideFooter: true,
    commitOnScroll: true,
    hideDisabled: true,
    ignoreOutsideClick: false
  },
  
  // Labels options
  labels: {
    ok: 'Confirm',
    cancel: 'Close',
    time: 'Choose Time',
    am: 'AM',
    pm: 'PM',
    mobileTime: 'Enter Time',
    mobileHour: 'Hour',
    mobileMinute: 'Minute'
  },
  
  // Behavior options
  behavior: {
    focusTrap: true,
    focusInputAfterClose: false,
    delayHandler: 300,
    id: 'my-timepicker'
  },
  
  // Callbacks options
  callbacks: {
    onConfirm: (data) => console.log('Confirmed:', data),
    onCancel: () => console.log('Cancelled'),
    onOpen: () => console.log('Opened'),
    onUpdate: (data) => console.log('Updated:', data),
    onSelectHour: (data) => console.log('Hour selected:', data.hour),
    onSelectMinute: (data) => console.log('Minute selected:', data.minutes),
    onError: (data) => console.error('Error:', data.error)
  }
});

```

--------------------------------

### Import All Themes

Source: https://timepicker-ui.vercel.app/docs/features/themes

Import all available themes to include all styles. This results in the largest bundle size.

```typescript
import 'timepicker-ui/index.css';
```

--------------------------------

### Initialize Timepicker UI with Configuration

Source: https://timepicker-ui.vercel.app/docs/configuration

Configure Timepicker UI with options for clock settings, UI theme, wheel behavior, labels, interaction behavior, and callback functions.

```typescript
const picker = new TimepickerUI(input, {
  clock: {
    type: '24h',
    incrementHours: 1,
    incrementMinutes: 5,
    autoSwitchToMinutes: false,
    disabledTime: {
      hours: [0, 1, 2, 3],
      interval: ['12:00 PM - 1:00 PM']
    }
  },
  ui: {
    theme: 'dark',
    animation: true,
    backdrop: true,
    mobile: false,
    editable: false,
    enableScrollbar: false,
    enableSwitchIcon: true,
  },
  wheel: {
    placement: 'bottom',
    hideFooter: true,
    commitOnScroll: true
  },
  labels: {
    ok: 'Confirm',
    cancel: 'Close',
    time: 'Choose Time'
  },
  behavior: {
    focusTrap: true,
    focusInputAfterClose: false,
    delayHandler: 300
  },
  callbacks: {
    onConfirm: (data) => console.log('Confirmed:', data),
    onCancel: () => console.log('Cancelled'),
    onUpdate: (data) => console.log('Updated:', data)
  }
});
```

--------------------------------

### Enable Blueprint Theme

Source: https://timepicker-ui.vercel.app/docs/whats-new

Enable the new 'blueprint' theme for a light precision-instrument look. This theme is tree-shakeable.

```javascript
ui.theme: 'blueprint'
```

--------------------------------

### Detect wheel:scroll:start Event

Source: https://timepicker-ui.vercel.app/docs/api/events

This event is triggered when a wheel column begins scrolling in wheel mode. It provides the name of the column that started scrolling.

```typescript
picker.on('wheel:scroll:start', (data) => {
  console.log('Scroll started on column:', data.column);
  // data.column: 'hours' | 'minutes' | 'ampm'
});
```

--------------------------------

### v3 Timepicker UI Initialization with Callbacks and EventEmitter

Source: https://timepicker-ui.vercel.app/docs/legacy-migration

Demonstrates initializing Timepicker UI in version 3 using a modern callback-based API for 'onOpen', 'onConfirm', and 'onCancel' events. It also shows how to use the recommended EventEmitter API for 'confirm' and 'once' events.

```javascript
import { TimepickerUI } from 'timepicker-ui';
import 'timepicker-ui/main.css'; // Required in v3

const input = document.querySelector('#myInput');

// v3 initialization with callbacks
const picker = new TimepickerUI(input, {
  clockType: '12h',
  theme: 'basic',
  // Modern callback-based API
  onOpen: () => {
    console.log('Opened');
  },
  onConfirm: (data) => {
    console.log('Time selected:', data);
  },
  onCancel: () => {
    console.log('Cancelled');
  },
});

// Or use EventEmitter API (recommended)
picker.on('confirm', (data) => {
  console.log('Confirmed:', data);
});

picker.once('open', () => {
  console.log('First open only');
});
```

--------------------------------

### create()

Source: https://timepicker-ui.vercel.app/docs/api/methods

Initializes the timepicker. This method must be called before using any other methods on the instance.

```APIDOC
## `create()`

### Description
Initialize the timepicker. Must be called before using other methods.

### Method
`create()`

### Example
```typescript
const picker = new TimepickerUI(input);
picker.create();
```
```

--------------------------------

### ARIA Labels

Source: https://timepicker-ui.vercel.app/docs/advanced/accessibility

Example of setting ARIA labels for the timepicker controls.

```typescript
const picker = new TimepickerUI(input, {
  labels: {
    // Visible button text (also announced by screen readers)
    ok: 'Confirm',
    cancel: 'Cancel',

    // Accessible names for the picker controls
    clockLabel: 'Clock',
    hourLabel: 'Hour',
    minuteLabel: 'Minute'
  }
});
```

--------------------------------

### Get All Timepicker Instances

Source: https://timepicker-ui.vercel.app/docs/api/methods

Retrieves an array containing all currently active TimepickerUI instances on the page.

```typescript
const allPickers = TimepickerUI.getAllInstances();
console.log(allPickers.length);
```

--------------------------------

### Get Root Wrapper Element

Source: https://timepicker-ui.vercel.app/docs/api/methods

Retrieves the root DOM element that wraps the timepicker component.

```typescript
const wrapper = picker.getElement();
```

--------------------------------

### Dynamic Disabled Time

Source: https://timepicker-ui.vercel.app/docs/features/disabled-time

Example of dynamically updating disabled time restrictions based on user actions, such as selecting a date.

```typescript
const input = document.querySelector('#timepicker');
const picker = new TimepickerUI(input);

// Initial creation with no restrictions
picker.create();

// Update to add restrictions (e.g., after selecting a date)
function updateTimeRestrictions(selectedDate) {
  const isWeekend = [0, 6].includes(selectedDate.getDay());
  
  const restrictions = isWeekend
    ? { hours: [] }  // No restrictions
    : { hours: [] };

  picker.update({
    options: {
      clock: {
        disabledTime: restrictions
      }
    },
    create: true
  });
}

// Listen for date changes
dateInput.addEventListener('change', (e) => {
  updateTimeRestrictions(new Date(e.target.value));
});
```

--------------------------------

### v3 Recommended Callbacks API

Source: https://timepicker-ui.vercel.app/docs/legacy-migration

The recommended v3 API uses callbacks like onConfirm, onCancel, and onOpen for a cleaner interface.

```javascript
const picker = new TimepickerUI(input, {
  onConfirm: (data) => {
    console.log('Time:', data);
  },
  onCancel: (data) => {
    console.log('Cancelled');
  },
  onOpen: () => {
    console.log('Opened');
  },
});
```

--------------------------------

### Updated Event Names in v3

Source: https://timepicker-ui.vercel.app/docs/legacy-migration

In v3, event names are prefixed with 'timepicker:'. This example shows the new event names.

```javascript
input.addEventListener('timepicker:open', (e) => {
  console.log('Opened');
});

input.addEventListener('timepicker:confirm', (e) => {
  console.log('Confirmed:', e.detail);
});

input.addEventListener('timepicker:cancel', (e) => {
  console.log('Cancelled');
});
```

--------------------------------

### Configure Compact Wheel Mode

Source: https://timepicker-ui.vercel.app/docs/whats-new

Use compact-wheel mode for a headerless picker and control popover placement with options like 'auto', 'top', or 'bottom'.

```javascript
compact-wheel mode
ui.placement: 'auto'
```

--------------------------------

### v2 Timepicker UI Initialization and Events

Source: https://timepicker-ui.vercel.app/docs/legacy-migration

This snippet shows the initialization of Timepicker UI in version 2, including configuration options like clock type and theme. It also demonstrates how to listen for 'show', 'accept', and 'cancel' events using event listeners.

```javascript
import { TimepickerUI } from 'timepicker-ui';

const input = document.querySelector('#myInput');

// v2 initialization
const picker = new TimepickerUI(input, {
  clockType: '12h',
  theme: 'basic',
});

// v2 events
input.addEventListener('show', () => {
  console.log('Opened');
});

input.addEventListener('accept', (e) => {
  console.log('Time selected:', e.detail);
});

input.addEventListener('cancel', () => {
  console.log('Cancelled');
});
```

--------------------------------

### switch:view

Source: https://timepicker-ui.vercel.app/docs/api/events

Triggered when switching between the clock and keyboard views.

```APIDOC
## switch:view

### Description
Triggered when switching between clock and keyboard view. The payload is empty.

### Event Name
`switch:view`

### Payload
Empty

### Request Example
```typescript
picker.on('switch:view', () => {
  console.log('View switched');
});
```
```

--------------------------------

### Get Timepicker Instance by ID

Source: https://timepicker-ui.vercel.app/docs/api/methods

Retrieves a specific TimepickerUI instance using its unique ID. This is useful for managing multiple instances.

```typescript
const picker = new TimepickerUI(input, { id: 'my-picker' });
picker.create();

const instance = TimepickerUI.getById('my-picker');
```

--------------------------------

### Create a Custom Theme with CSS Variables

Source: https://timepicker-ui.vercel.app/docs/advanced/styling

Define a custom theme by applying the 'custom' class to the wrapper and overriding specific CSS variables. This allows for unique branding.

```css
/* Override CSS variables in the custom theme wrapper */
.tp-ui-wrapper.custom {
  --tp-bg: #ffffff;
  --tp-text: #000000;
  --tp-primary: #6200ee;
  --tp-on-primary: #ffffff;
  --tp-surface: #e0e0e0;
  --tp-surface-hover: #ece0fd;
  --tp-input-bg: #e4e4e4;
  --tp-border: #d6d6d6;
  --tp-hover-bg: #d6d6d6;
  --tp-text-secondary: #a9a9a9;
  --tp-text-type-time: #787878;
  --tp-text-icon: #4e545a;
  --tp-text-disabled: rgba(156, 155, 155, 0.6);
  --tp-shadow: 0 10px 35px 0 rgba(0, 0, 0, 0.25);
  --tp-border-radius: 4px;
  --tp-font-family: 'Roboto', sans-serif;
}
```

--------------------------------

### Apply a Theme

Source: https://timepicker-ui.vercel.app/docs/features/themes

Apply a theme by setting the `theme` option during TimepickerUI initialization.

```typescript
const picker = new TimepickerUI(input, {
  ui: {
    theme: 'cyberpunk'
  }
});
picker.create();
```

--------------------------------

### Event Names Prefixed in v3

Source: https://timepicker-ui.vercel.app/docs/legacy-migration

All event names in v3 are prefixed with 'timepicker:' to avoid conflicts. This example shows the v2 event names.

```javascript
input.addEventListener('show', (e) => {
  console.log('Opened');
});

input.addEventListener('accept', (e) => {
  console.log('Confirmed:', e.detail);
});

input.addEventListener('cancel', (e) => {
  console.log('Cancelled');
});
```

--------------------------------

### Handle 'range:confirm' event

Source: https://timepicker-ui.vercel.app/docs/api/events

This event is for the range mode and is triggered when a time range is confirmed. The payload includes the start and end times, and the duration in minutes.

```typescript
picker.on('range:confirm', (data) => {
  console.log('From:', data.from, 'To:', data.to);
  console.log('Duration (minutes):', data.duration);
});
```

--------------------------------

### Import Timepicker-UI Styles

Source: https://timepicker-ui.vercel.app/docs/installation

Import the library's main CSS file into your project's entry point.

```typescript
import "timepicker-ui/main.css";
```

--------------------------------

### Validate Time Range

Source: https://timepicker-ui.vercel.app/docs/features/validation

Checks if a selected time falls within a specified start and end time. Utilizes the `timeToMinutes` helper function for accurate comparisons.

```typescript
function isTimeInRange(time, startTime, endTime) {
  const selected = timeToMinutes(time);
  const start = timeToMinutes(startTime);
  const end = timeToMinutes(endTime);
  
  return selected >= start && selected <= end;
}

function timeToMinutes(time) {
  const [hours, minutes] = time.split(':').map(Number);
  return hours * 60 + minutes;
}

// Validate on accept
input.addEventListener('accept', (event) => {
  const time = event.detail.hour + ':' + event.detail.minutes;
  
  if (!isTimeInRange(time, '09:00', '17:00')) {
    showError('Please select a time between 9:00 AM and 5:00 PM');
    return;
  }
  
  submitTime(time);
});
```

--------------------------------

### TypeScript Error Handling

Source: https://timepicker-ui.vercel.app/docs/api/typescript

Configure Timepicker UI to handle errors gracefully using the `onError` callback. This example shows logging the error and alerting the user.

```typescript
import type { ConfirmEventData, ErrorEventData } from 'timepicker-ui';
import { TimepickerUI } from 'timepicker-ui';

const picker = new TimepickerUI('#timepicker', {
  callbacks: {
    onError: (data: ErrorEventData) => {
      console.error('Timepicker error:', data.error);
      alert(`Invalid time format: ${data.error}`);
    },
    onConfirm: (data: ConfirmEventData) => {
      console.log('Time confirmed:', `${data.hour}:${data.minutes}`);
    }
  }
});
```

--------------------------------

### Handle Range Confirmation with onRangeConfirm Callback

Source: https://timepicker-ui.vercel.app/docs/api/events

This callback option is triggered when a range is confirmed in range mode. It provides the start and end times of the range, along with the duration.

```typescript
new TimepickerUI(input, {
  callbacks: {
    onRangeConfirm: (data) => {
      console.log('Range:', data.from, '-', data.to, data.duration);
    }
  }
});
```

--------------------------------

### open

Source: https://timepicker-ui.vercel.app/docs/api/events

Triggered when the timepicker opens. Provides details about the initial time and degrees.

```APIDOC
## open

### Description
Triggered when the picker opens. The payload includes initial time and degree information.

### Event Name
`open`

### Payload
* **data** (object)
  * **hour** (number) - The initial hour.
  * **minutes** (number) - The initial minutes.
  * **type** (string) - 'AM' or 'PM' (in 12-hour mode).
  * **degreesHours** (number) - The initial hour in degrees.
  * **degreesMinutes** (number) - The initial minutes in degrees.

### Request Example
```typescript
picker.on('open', (data) => {
  console.log('Picker opened');
  console.log(data.hour, data.minutes, data.type);
  console.log(data.degreesHours, data.degreesMinutes);
});
```
```

--------------------------------

### Extending TypeScript Types

Source: https://timepicker-ui.vercel.app/docs/api/typescript

Create a custom wrapper class that extends Timepicker UI's functionality and types. This example adds analytics tracking to the confirmation callback.

```typescript
import type { TimepickerOptions, ConfirmEventData } from 'timepicker-ui';
import { TimepickerUI } from 'timepicker-ui';

// Extend options with custom properties
interface CustomTimepickerOptions extends TimepickerOptions {
  analyticsEnabled?: boolean;
}

// Create wrapper with custom logic
class CustomTimepicker {
  private picker: TimepickerUI;
  private analyticsEnabled: boolean;

  constructor(
    input: HTMLInputElement,
    options: CustomTimepickerOptions
  ) {
    const { analyticsEnabled, ...pickerOptions } = options;
    this.analyticsEnabled = analyticsEnabled ?? false;

    const finalOptions: TimepickerOptions = {
      ...pickerOptions,
      callbacks: {
        ...pickerOptions.callbacks,
        onConfirm: (data: ConfirmEventData) => {
          if (this.analyticsEnabled) {
            this.trackEvent('time_confirmed', data);
          }
          pickerOptions.callbacks?.onConfirm?.(data);
        }
      }
    };

    this.picker = new TimepickerUI(input, finalOptions);
  }

  private trackEvent(event: string, data: ConfirmEventData) {
    console.log('Analytics:', event, data);
  }

  create() {
    this.picker.create();
  }

  destroy() {
    this.picker.destroy();
  }
}
```

--------------------------------

### Set Timepicker UI Theme

Source: https://timepicker-ui.vercel.app/docs/api/options

Configure the visual theme of the Timepicker UI by setting the 'theme' option within the 'ui' object. This example sets the theme to 'cyberpunk'.

```typescript
const picker = new TimepickerUI(input, {
  ui: { theme: 'cyberpunk' }
});
```

--------------------------------

### Initialize Timepicker-UI with Default Settings

Source: https://timepicker-ui.vercel.app/docs/quick-start

Basic JavaScript initialization of Timepicker-UI on an HTML input element. Ensure the 'timepicker-ui' package is imported.

```typescript
import { TimepickerUI } from 'timepicker-ui';

const input = document.querySelector('#timepicker');
const picker = new TimepickerUI(input);
picker.create();

```

--------------------------------

### Keyboard navigation test with React Testing Library

Source: https://timepicker-ui.vercel.app/docs/advanced/accessibility

Uses @testing-library/react and user-event to simulate keyboard interaction with the Timepicker component. Verifies that the modal opens on Enter and that arrow key navigation works. Requires the TimepickerComponent to be rendered and accessible via a textbox role.

```javascript
// Using @testing-library for keyboard testing
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';

test('can navigate with keyboard', async () => {
  const user = userEvent.setup();
  render(<TimepickerComponent />);
  
  const input = screen.getByRole('textbox');
  await user.click(input);
  await user.keyboard('{Enter}');
  
  // Verify modal opened
  expect(screen.getByRole('dialog')).toBeInTheDocument();
  
  // Test arrow key navigation
  await user.keyboard('{ArrowUp}');
  await user.keyboard('{Enter}');
});
```

--------------------------------

### Get Current Time Value

Source: https://timepicker-ui.vercel.app/docs/api/methods

Retrieves the currently selected time value from the timepicker. The returned object contains detailed time components and their corresponding degree values.

```typescript
const value = picker.getValue();

{
  hour: '10',
  minutes: '30',
  type: 'AM',
  time: '10:30 AM',
  degreesHours: 300,
  degreesMinutes: 180
}
```

--------------------------------

### Register and Use Wheel Plugin (Full and Compact Modes)

Source: https://timepicker-ui.vercel.app/docs/features/plugins

Replaces the analog clock with a touch-friendly scroll-spinner. Supports 'wheel' mode with a header or 'compact-wheel' mode as a headerless popover. Configure placement and auto-commit on scroll.

```javascript
import { TimepickerUI, PluginRegistry } from 'timepicker-ui';
import { WheelPlugin } from 'timepicker-ui/plugins/wheel';
import 'timepicker-ui/main.css';

PluginRegistry.register(WheelPlugin);

// Full wheel mode (with header)
const picker = new TimepickerUI(input, {
  ui: { mode: 'wheel' }
});
picker.create();

// Compact-wheel popover (headerless, anchored to input)
const popoverPicker = new TimepickerUI(input2, {
  ui: { mode: 'compact-wheel' },
  wheel: {
    placement: 'auto',      // 'auto', 'top', or 'bottom'
    commitOnScroll: true,    // auto-confirm on scroll stop
    ignoreOutsideClick: false
  }
});
popoverPicker.create();

```

--------------------------------

### Basic TypeScript Initialization

Source: https://timepicker-ui.vercel.app/docs/api/typescript

Initialize Timepicker UI with custom options for theme, clock type, and confirmation callbacks. Ensure the target input element exists in the DOM.

```typescript
import { TimepickerUI } from 'timepicker-ui';
import type { TimepickerOptions, ConfirmEventData } from 'timepicker-ui';

const options: TimepickerOptions = {
  ui: { theme: 'dark' },
  clock: { type: '24h' },
  callbacks: {
    onConfirm: (data: ConfirmEventData) => {
      console.log(`Time: ${data.hour}:${data.minutes}`);
    }
  }
};

const input = document.querySelector<HTMLInputElement>('#timepicker');
if (input) {
  const picker = new TimepickerUI(input, options);
  picker.create();
}
```

--------------------------------

### Dynamic Theme Switching

Source: https://timepicker-ui.vercel.app/docs/features/themes

Change themes at runtime using the `update` method. Ensure `create: true` is set to re-render the picker with the new theme.

```typescript
// Initialize with basic theme
const picker = new TimepickerUI(input, {
  ui: {
    theme: 'basic'
  }
});
picker.create();

// Switch to dark theme
picker.update({
  options: { ui: { theme: 'dark' } },
  create: true
});

// Switch to cyberpunk theme
picker.update({
  options: { ui: { theme: 'cyberpunk' } },
  create: true
});
```

--------------------------------

### Configure Wheel Mode

Source: https://timepicker-ui.vercel.app/docs/api/options

Set the UI mode to 'wheel' or 'compact-wheel'. Configures popover placement, hides the footer, and enables committing values on scroll end.

```typescript
const picker = new TimepickerUI(input, {
  ui: { mode: 'wheel' },
  wheel: {
    placement: 'bottom',     // Popover placement (compact-wheel only)
    hideFooter: true,        // Hide OK/Cancel footer
    commitOnScroll: true     // Commit value on scroll end
  }
});

```

--------------------------------

### Configure Inline Timepicker with Disabled Hours and Minutes

Source: https://timepicker-ui.vercel.app/docs/features/inline-mode

This example demonstrates how to restrict time selection in an inline timepicker by disabling specific hours (0-5 and 22-23) and minutes (15, 30, 45).

```typescript
const picker = new TimepickerUI(input, {
  ui: { enableSwitchIcon: false },
  clock: {
    disabledTime: {
      hours: [0, 1, 2, 3, 4, 5, 22, 23],
      minutes: [15, 30, 45]
    }
  }
});

picker.create();
```

--------------------------------

### Get and Set Timepicker Values

Source: https://timepicker-ui.vercel.app/docs/legacy-migration

Shows how to programmatically retrieve the current time value from a Timepicker UI instance and how to set a new time value, including support for different time formats.

```javascript
const picker = new TimepickerUI('#input');

const currentTime = picker.getValue();
console.log(currentTime); // "14:30"

picker.setValue('09:15');

picker.setValue('3:45 PM');
```

--------------------------------

### Clock Options

Source: https://timepicker-ui.vercel.app/docs/api/options

Configure the behavior and time settings of the clock interface.

```APIDOC
## Clock Options

Clock behavior and time configuration options:

| Option | Type | Default | Description |
|---|---|---|---|
| `type` | "12h" | "12h" | Clock format type |
| `incrementHours` | number | 1 | Hour increment step (1, 2, 3, etc.) |
| `incrementMinutes` | number | 1 | Minute increment step (1, 5, 10, 15, etc.) |
| `autoSwitchToMinutes` | boolean | true | Auto-switch to minutes after hour selection |
| `disabledTime` | DisabledTime | undefined | Disable specific hours, minutes, or intervals |
| `smoothHourSnap` | boolean | true | Enable smooth hour dragging with snap animation |
| `currentTime` | CurrentTime | undefined | Set current time configuration |
```

--------------------------------

### Change clock format dynamically with picker.update()

Source: https://timepicker-ui.vercel.app/docs/features/clock-format

Changes the clock format at runtime. Starts with 12-hour format, then calls picker.update() with options.clock.type set to '24h' and create: true to switch to 24-hour format after the picker is created.

```typescript
// Start with 12h format
const picker = new TimepickerUI(input, {
  clock: {
    type: '12h'
  }
});
picker.create();

// Switch to 24h format
picker.update({
  options: { clock: { type: '24h' } },
  create: true
});
```

--------------------------------

### Import Base and Specific Theme

Source: https://timepicker-ui.vercel.app/docs/features/themes

Import the base styles along with a specific theme's CSS file. This is the recommended approach for reducing bundle size while using a custom theme.

```typescript
import 'timepicker-ui/main.css';
import 'timepicker-ui/theme-cyberpunk.css';
```

--------------------------------

### Using Language Configs with Timepicker UI

Source: https://timepicker-ui.vercel.app/docs/advanced/localization

Demonstrates how to use a pre-defined language configuration object (Spanish in this case) when initializing Timepicker UI. This approach promotes code reusability and consistency. Ensure the 'input' element is defined and the locale file is correctly imported.

```typescript
import TimepickerUI from 'timepicker-ui';
import { esLocale } from './locales/es';

const picker = new TimepickerUI(input, {
  ...esLocale,
  clock: { type: '24h' }
});

picker.create();
```

--------------------------------

### Use Timepicker-UI via CDN

Source: https://timepicker-ui.vercel.app/docs/installation

For rapid prototyping, include the Timepicker-UI CSS and JavaScript from a CDN. The UMD build exposes the TimepickerUI class globally.

```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/timepicker-ui@4.4.0/dist/css/main.css">
<script src="https://cdn.jsdelivr.net/npm/timepicker-ui@4.4.0/dist/index.umd.js"></script>
<script>
  // The UMD build exposes the class as the global TimepickerUI
  const picker = new TimepickerUI('#timepicker');
  picker.create();
</script>
```

--------------------------------

### TimepickerUI.getAllInstances()

Source: https://timepicker-ui.vercel.app/docs/api/methods

Retrieves all currently active TimepickerUI instances.

```APIDOC
## `TimepickerUI.getAllInstances()`

### Description
Get all currently active TimepickerUI instances.

### Method
`TimepickerUI.getAllInstances()`

### Example
```typescript
const allPickers = TimepickerUI.getAllInstances();
console.log(allPickers.length);
```
```
Tokens:
Raw