TimeRangePicker

A relative/absolute time-range picker — quick presets like “Past 15 minutes” plus a custom calendar + time entry mode for exact date ranges, similar to what you’d find in an observability dashboard.

Import

import { TimeRangePicker } from '@flxui/uikit/business'

Basic Usage

import { useState } from 'react'
import { TimeRangePicker, TimeRange } from '@flxui/uikit/business'
 
function Demo() {
  const [value, setValue] = useState<TimeRange>()
  return <TimeRangePicker value={value} onChange={setValue} />
}

Quick Ranges

By default the dropdown lists DEFAULT_QUICK_RANGES — 5m, 15m, 30m, 1h, 3h, 12h, 24h, 2d, 3d, each rendered as “Past X”. Override with quickRanges, mixing plain numbers (seconds) and richer objects:

<TimeRangePicker
  value={value}
  onChange={setValue}
  quickRanges={[
    5 * 60,
    30 * 60,
    { value: 60 * 60, label: 'Last hour' },
    { value: 60 * 60, isFuture: true, label: 'Next hour' }
  ]}
/>

Clearable

<TimeRangePicker value={value} onChange={setValue} clearable />

An ”×” appears in the trigger button on hover once a value is set; clicking it calls onChange() with no arguments (i.e. undefined), not onChange(null).

Custom (Absolute) Range

Clicking “Custom” in the dropdown switches to a calendar + start/end date-and-time entry view, built on the package’s DatePicker in range mode. It validates as you go:

• start after end
• start earlier than minDateTime()
• end later than maxDateTime()
• selected span longer than maxDuration (seconds)

The Apply button stays disabled until both ends are picked and no validation error is active.

<TimeRangePicker
  value={value}
  onChange={setValue}
  minDateTime={() => new Date('2024-01-01')}
  maxDateTime={() => new Date()}
  maxDuration={7 * 24 * 60 * 60} // 7 days, in seconds
/>

You can also pass datePickerProps (forwarded to the underlying range DatePicker) or dateInputFormat (a (date: Date) => string formatter for the two read-only date fields above the calendar).

Disable Absolute Ranges

Hide the “Custom” entry and only offer the quick relative presets — also switches the dropdown to a narrower, compact width:

<TimeRangePicker value={value} onChange={setValue} disableAbsoluteRanges />

Localization

<TimeRangePicker
  value={value}
  onChange={setValue}
  localization={{
    entry: 'Custom range',
    back: 'Back',
    start: 'From',
    end: 'To',
    apply: 'Apply',
    cancel: 'Cancel',
    errors: {
      startAfterEnd: 'End must be after start.',
      beyondMin: (min) => `Start must be after ${min.toLocaleDateString()}`,
      beyondMax: (max) => `End must be before ${max.toLocaleDateString()}`,
      beyondDuration: (seconds) => `Range can't exceed ${seconds / 3600} hours.`
    }
  }}
/>

All localization keys are optional — anything omitted falls back to the English default shown in the source.

Display Timezone

timezone (a UTC offset in hours) only affects how the absolute trigger text and tooltip are formatted — it doesn’t affect what gets stored in value, and it has no effect on relative ranges like “Past 15 minutes”:

<TimeRangePicker value={value} onChange={setValue} timezone={8} />

For actually editing and storing values in a specific timezone (not just display), use useTimeRangePicker below.

Timezone-Aware Editing with useTimeRangePicker

useTimeRangePicker converts value, onChange, minDateTime/maxDateTime, and the formatter props between a target utcOffset and the browser’s local time — the picker’s calendar/time inputs behave as if the user is in that timezone, while what you receive in onChange (for absolute ranges) is expressed in the target offset too:

import { useState } from 'react'
import { TimeRangePicker, useTimeRangePicker, TimeRange } from '@flxui/uikit/business'
 
function Demo() {
  const [value, setValue] = useState<TimeRange>()
 
  const pickerProps = useTimeRangePicker({
    value: value ?? { type: 'relative', value: 1800 },
    onChange: setValue,
    utcOffset: 480, // UTC+8, in minutes
    minDateTime: () => new Date('2024-01-01'),
    maxDateTime: () => new Date()
  })
 
  return <TimeRangePicker {...pickerProps} />
}

Props

TimeRangePickerProps extends TimeRangePickerBaseProps, which itself extends ButtonProps (the trigger is a Button, and props like variant or size pass straight through and override the component’s own defaults).

The TimeRange Type

type TimeRange = RelativeTimeRange | AbsoluteTimeRange
 
interface RelativeTimeRange {
  type: 'relative'
  value: number // duration in seconds
  isFuture?: boolean // "next X" vs "past X"
  utcOffset?: number | string
}
 
interface AbsoluteTimeRange {
  type: 'absolute'
  value: [from: number, to: number] // unix seconds
}

Utility Functions

These are re-exported alongside TimeRangePicker from the same import path, so import { TimeRangePicker, formatDuration } from '@flxui/uikit/business' works.

useTimeRangePicker Reference

Returns an object spreadable directly onto <TimeRangePicker />: value, onChange, minDateTime, maxDateTime, maxDuration, relativeFormatter, absoluteFormatter, dateInputFormat, timezone.