DateRangeBar
The period a report covers: a range with presets or two dates, the interval its charts group by, and what it's compared with.
import { DateRangeBar } from "@butteryui/react";Demo
When to use it
Use it for
- Above an overview's metric cards and charts, to set the period they all show
- A report page that fetches its data for a range and a comparison
Not for
- Picking one date in a form: use a TextField with type="date"
- Filtering a table by date: use a FilterPill
Examples
Default period
With no props it keeps its own value, starting on the last 7 days, daily, against the previous period.
Overview metrics
An overview's period over its metric cards: a new range changes their numbers, and No comparison drops the change.
Revenue
$3,180.00
vs previous period
Orders
71
vs previous period
Overview period
The period an overview shows, kept in state and turned into the query that fetches its numbers.
Fetching /api/overview?range=last-4-weeks&interval=weekly&compare=previous-period
Spanish labels
The bar in Spanish, with its own words for every part.
Variants and states
Presets, an interval and a comparison
Open the range for presets or two dates of your own; under 640px of room the comparison moves to its own row.
A custom range
Props
DateRangeBar
| Prop | Type | Default | Description |
|---|---|---|---|
value | DateRangeValue | What it's set to, when you control it. | |
defaultValue | DateRangeValue | What it starts at. Defaults to the last 7 days, daily, against the previous period. | |
onValueChange | ((value: DateRangeValue) => void) | Called with everything it's set to whenever one part changes. | |
label | string | "Period" | Names the group. Defaults to "Period". |
labels | Partial<DateRangeBarLabels> | Its words, for another language or your own names. | |
formatRange | ((range: CustomDateRange) => string) | Writes a custom range on the range select. Defaults to the short month and days, such as "Oct 1 – 14". |
It also takes Omit<ComponentPropsWithRef<"div">, "defaultValue">.
DateRangeValue
Everything a `DateRangeBar` is set to, for fetching a report's data.
| Field | Type | Default | Description |
|---|---|---|---|
rangerequired | "today" | "last-7-days" | "last-4-weeks" | "last-3-months" | "last-12-months" | "month-to-date" | "year-to-date" | "custom" | The range: a preset ending today, or "custom". | |
custom | CustomDateRange | The dates of a "custom" range. | |
intervalrequired | "daily" | "weekly" | "monthly" | How the charts group their points. | |
comparisonrequired | "previous-period" | "previous-year" | "none" | What the period is compared with. |
DateRangeBarLabels
The words a `DateRangeBar` shows and announces.
| Field | Type | Default | Description |
|---|---|---|---|
rangerequired | string | Names the range select. | |
intervalrequired | string | Names the interval select. | |
comparisonrequired | string | Names the comparison select. | |
comparedTorequired | string | The caption before the comparison select. | |
customRangerequired | string | Names the custom range fields under the range list. | |
startrequired | string | Labels the first date field. | |
endrequired | string | Labels the last date field. | |
presetsrequired | Readonly<Record<DateRangePreset, string>> | Each range's name in the list. | |
intervalsrequired | Readonly<Record<DateInterval, string>> | Each interval's name in the list. | |
comparisonsrequired | Readonly<Record<DateComparison, string>> | Each comparison's name in the list. |
CustomDateRange
Two dates as ISO strings, such as `"2026-10-01"`, the end on or after the start.
| Field | Type | Default | Description |
|---|---|---|---|
startrequired | string | The first day, as YYYY-MM-DD. | |
endrequired | string | The last day, as YYYY-MM-DD. |
Accessibility
A group named Period holding three selects, each named by what it sets and its current choice. The range list ends with two date fields for a custom range, which Tab reaches from the list. The "compared to" caption is hidden from screen readers, since the comparison select says it.
| Keys | What they do |
|---|---|
| Enter, Space, ArrowDown or ArrowUp | Opens the focused select's list, with focus on its choice |
| ArrowDown, ArrowUp, Home or End | Moves through the list's options |
| A letter | Moves to the option that starts with it |
| Enter or Space | Chooses the option and closes the list, focus back on the select |
| Tab | Moves from the range's list to its two date fields and back |
| Escape | Closes the list and puts focus back on the select |
Motion
It doesn't move.
With reduced motion: Nothing changes.
Layout
It fills the width it's given, asking for 640px in a row: three 28px outline selects (--bt-h-sm) 8 apart, the comparison after its caption. Under 640px of its own width the range and the interval share a row in equal halves over the comparison.
Related
See it in the roastery demo's overview.