PeriodPicker

Pick a year, quarter, month or week from one control.

SourcePackage @weft-js/warp

Preview

tsx

import { state } from '@weft-js/core'import { PeriodPicker, Stack, Text } from '@weft-js/warp'import type { IsoDate } from '@weft-js/warp'export function Report() {  const period = state<string | null>('2026-Q4')  return (    <Stack gap="related">      <PeriodPicker label="Report period" today={TODAY} value={period} />      <Text subtle role="caption">Saved as {period.value ?? 'nothing'}</Text>    </Stack>  )}const TODAY: IsoDate = '2026-11-02'

Installation

npm install @weft-js/warp

Usage

tsx

import { PeriodPicker } from '@weft-js/warp'

Each granularity

Use granularity to pick year, quarter, month or week.

tsx

import { PeriodPicker, Stack } from '@weft-js/warp'import type { IsoDate } from '@weft-js/warp'export function Granularity() {  return (    <Stack gap="group">      <PeriodPicker label="Year" today={TODAY} defaultValue="2026" granularity="year" />      <PeriodPicker label="Quarter" today={TODAY} defaultValue="2026-Q4" granularity="quarter" />      <PeriodPicker label="Month" today={TODAY} defaultValue="2026-10" granularity="month" />      <PeriodPicker label="Week" today={TODAY} defaultValue="2026-W45" granularity="week" />    </Stack>  )}const TODAY: IsoDate = '2026-11-02'

Hint, error, read-only, disabled

The same hint, error, readonly and disabled as every field.

tsx

import { PeriodPicker, Stack, Text, Grid } from '@weft-js/warp'import type { IsoDate } from '@weft-js/warp'export function States() {  return (    <Grid cols={2} gap="group">      <Cell name="Empty"><PeriodPicker label="Period" today={TODAY} granularity="quarter" /></Cell>      <Cell name="Hint"><PeriodPicker label="Period" today={TODAY} granularity="quarter" hint="Closed quarters only." /></Cell>      <Cell name="Invalid"><PeriodPicker label="Period" today={TODAY} defaultValue="2027-Q1" error="That quarter hasn't started." /></Cell>      <Cell name="Read-only"><PeriodPicker label="Period" today={TODAY} defaultValue="2026-Q3" readonly /></Cell>      <Cell name="Disabled"><PeriodPicker label="Period" today={TODAY} defaultValue="2026-Q3" disabled /></Cell>    </Grid>  )}const TODAY: IsoDate = '2026-11-02'const Cell = (p: { name: string; children?: unknown }) => (  <Stack gap="tight">    <Text role="caption" subtle>{p.name}</Text>    {p.children}  </Stack>)

A report header

One control picks a year, a quarter or a month, and the figure below reads the value.

tsx

import { state } from '@weft-js/core'import { Card, PeriodPicker, Stack, Text } from '@weft-js/warp'import type { IsoDate } from '@weft-js/warp'export function Revenue() {  const period = state<string | null>('2026-Q3')  const total = () => (period.value ? REVENUE[period.value] : undefined)  return (    <Stack gap="group">      <PeriodPicker label="Revenue for" today={TODAY} value={period} />      <Card>        <Stack gap="tight">          <Text role="label" subtle>Revenue, {period.value ?? 'no period'}</Text>          <Text role="heading">{total() === undefined ? 'No figures yet' : usd(total()!)}</Text>          <Text role="caption" subtle>Try 2026, 2026-Q1 to Q4, or September and October.</Text>        </Stack>      </Card>    </Stack>  )}const TODAY: IsoDate = '2026-11-02'const usd = (n: number) => `$${n.toLocaleString('en-US')}`const REVENUE: Record<string, number> = { '2026': 412300, '2026-Q1': 96400, '2026-Q2': 101800, '2026-Q3': 104900, '2026-Q4': 109200, '2026-10': 36100, '2026-09': 35200 }

When to use

Use it for

Reports that run by whole periods

Reach for something else

DateRangeField, when the range can start on any day

Accessibility

Arrows: Move between cells
PageUp/PageDown: Change the page
EnterorSpace: Picks the period

API Reference

Prop	Type	Default	Description
`label`	`string`	—	The accessible name, drawn as the floating border label (or above, classic). Required.
`hint`	`unknown`	—	One line of help under the control.
`error`	`unknown`	—	Shown instead of the hint; marks the field invalid.
`icon`	`IconRef`	—	Leading icon: it sweeps with the border.
`prefix`	`unknown`	—	Text or an element inside the field before the value, such as `$`.
`suffix`	`unknown`	—	Text or an element inside the field after the value, such as `kg`.
`variant`	`"floating" \| "classic"`	—	floating (default, or the app's `warp({ fields })`) · classic: the label above.
`appearance`	`"line"`	—	`line`: only a bottom line under the value, no box or fill. The boxed field otherwise.
`size`	`"sm" \| "md" \| "lg"`	`'md'`	Control size. `md` by default.
`clearable`	`boolean`	`false`	A clear button (shown once there is a value).
`counter`	`number`	—	Maximum length, shown as a counter.
`id`	`string`	—	The element id. One is made for you if you leave it out.
`disabled`	`boolean`	`false`	Turns it off, and takes it out of the tab order.
`readonly`	`boolean`	`false`	Shows the value and lets it be selected and copied, but not changed.
`required`	`boolean`	`false`	The form will not submit without it.
`name`	`string`	—	The name it posts under in a form.
`locale`	`string`	—	The language and region used to format values.
`today`	`string`	—	Pins "today" (server render, tests); the browser's clock otherwise.
`presentation`	`Presentation`	—	`auto` opens a popover, or a sheet when the viewport is under 600px wide; `popover` and `sheet` force one.
`value`	`string \| State<string \| null> \| null`	—	The current value, when you own the state.
`defaultValue`	`string \| null`	—	The starting value, when the component owns the state.
`open`	`boolean \| State<boolean>`	—	A state box that holds whether it is open.
`defaultOpen`	`boolean`	`false`	Starts open, when the component keeps its own open state.
`granularity`	`Granularity`	—	`year`, `quarter`, `month` or `week`.

Event	Type	Default	Description
`onInput`	`((e: InputEvent & { currentTarget: HTMLInputElement & HTMLTextAreaElemen…`	—	Called on each keystroke.
`onValueChange`	`((v: string \| null, reason: ChangeReason) => void)`	—	Called with each new value, and whether a pointer, a key or code made the change.
`onOpenChange`	`((o: boolean) => void)`	—	Called with `true` when it opens and `false` when it closes.