trPicker — Circular Time Range Picker

English | 简体中文

Version: 1.1.2

An SVG-based circular time-range picker supporting 24-hour / 12-hour modes. Select a time range by dragging the handles.

Quick start

Install

npm install trpicker

ES Module

import trPicker from 'trpicker';

const picker = new trPicker(document.getElementById('picker'), {
    hourCycle: 24,
    startMinute: 0,
    endMinute: 360,          // 06:00
    stepMinute: 10,
});

CommonJS

const trPicker = require('trpicker');

const picker = new trPicker(document.getElementById('picker'), {
    hourCycle: 24,
});

Browser <script> / CDN

The IIFE bundle exposes the global trPicker:

<!-- CDN (unpkg / jsdelivr) -->
<script src="https://unpkg.com/trpicker/dist/trpicker.iife.js"></script>
<!-- or -->
<script src="https://cdn.jsdelivr.net/npm/trpicker/dist/trpicker.iife.js"></script>
<!-- or locally -->
<script src="node_modules/trpicker/dist/trpicker.iife.js"></script>

<!-- 2. Container -->
<div id="picker" style="width:320px;height:320px;"></div>

<script>
const picker = new trPicker(document.getElementById('picker'), {
    hourCycle: 24,
    startMinute: 0,
    endMinute: 360,          // 06:00
    stepMinute: 10,
    onChange: (start, end) => {
        const fmt = m => `${String(Math.floor(m/60)).padStart(2,'0')}:${String(m%60).padStart(2,'0')}`;
        console.log(fmt(start), '-', fmt(end));
    },
});
</script>

Popup mode

<input type="text" id="trigger" readonly placeholder="Select a time range">

<script>
const picker = new trPicker(document.getElementById('trigger'), {
    hourCycle: 24,
    popup: true,
    onChange: (start, end) => {
        const fmt = m => `${String(Math.floor(m/60)).padStart(2,'0')}:${String(m%60).padStart(2,'0')}`;
        document.getElementById('trigger').value = `${fmt(start)} - ${fmt(end)}`;
    },
});
</script>

The popup panel is positioned directly below the trigger input by default, with a 4px gap. If the viewport does not leave enough space below, it automatically flips to appear above the input.

popupOffset (default 4) is a global appearance constant, not a constructor option. Adjust it before creating the picker: trPicker.APPEARANCE.popup.offset = 8;

Configuration options

| Option | Type | Default | Description | |--------|------|---------|-------------| | hourCycle | 12 \| 24 | 24 | Hour cycle | | startMinute | number | 0 | Initial start minute 0–1439 | | endMinute | number | 360 | Initial end minute 0–1439 | | startHour | number | — | Initial start hour (float, replaces startMinute) | | endHour | number | — | Initial end hour (float, replaces endMinute) | | stepMinute | number | 10 | Snap step (minutes) | | startColor | string | '#4f46e5' | Start handle color | | endColor | string | '#ef4444' | End handle color | | lineColor | string | '#28a050' | Arc color; 'gradient' for a gradient | | detailLevel | 'simple' \| 'detailed' | 'simple' | Dial tick detail level | | dialStyle | 'solid' \| 'metal' | 'solid' | Dial material style | | popup | boolean | false | Use popup mode | | popupAnimation | 'fade' \| 'drop' \| 'instant' | 'fade' | Popup animation | | popupBorderRadius | number | 16 | Popup panel corner radius (px) | | enableFineSlider | boolean | true | Show the fine slider | | enableModeSwitch | boolean | true | Show the 12/24H toggle in the UI | | enableStepAdjust | boolean | true | Show the step selector in the UI | | enableDetailAdjust | boolean | true | Show the detail toggle in the UI | | enableMinStep | boolean | true | Enforce a minimum interval >= stepMinute | | amText | string | 'AM' | AM label (12H) | | pmText | string | 'PM' | PM label (12H) | | onChange | fn(start, end) | — | Time change callback |

API

Methods

| Method | Description | |--------|-------------| | setStep(minute) | Change the snap step | | setStartColor(color) | Set the start color | | setEndColor(color) | Set the end color | | setLineColor(color) | Set the arc color; 'gradient' for a gradient | | setDetailLevel('simple'\|'detailed') | Switch the tick detail level | | setDialStyle('solid'\|'metal') | Switch the dial style | | setHourCycle(12\|24) | Switch the hour cycle | | getDateTimeValues(baseDate?) | Returns { startDay, endDay, durationMin } | | open() | Open the popup panel | | close() | Close the popup panel | | toggle() | Toggle the popup panel | | destroy() | Destroy the component and release resources |

Properties

| Property | Type | Description | |----------|------|-------------| | startMinute | number | Current start minute 0–1439 | | endMinute | number | Current end minute 0–1439 | | hourCycle | number | Current cycle 12 / 24 |

Styling

CSS class names are prefixed with trpicker-; override them to customize the appearance.

| Class | Purpose | |-------|---------| | .trpicker-popup | Popup panel container | | .trpicker-overlay | Popup overlay | | .trpicker-fine-slider | Fine slider | | .trpicker-hour | Dial numbers (defaults built-in as SVG attributes; override if needed) | | .trigger-input | Trigger input (defined by the consumer) |

The component does not touch the consumer's display styles. Format and update the UI yourself in the onChange callback.

Browser support

• Modern browsers (Chrome, Firefox, Safari, Edge)
• Requires SVG, Pointer Events, and Touch Events
• IE 11 and below are not supported