RecurrenceField

Build a repeating schedule, with the rule in plain words and the next dates listed.

SourcePackage @weft-js/warp

Preview

tsx

import { state } from '@weft-js/core'import { RecurrenceField, Stack, Tag } from '@weft-js/warp'export function Backup() {  const rule = state<string | null>('FREQ=WEEKLY;BYDAY=MO,TH')  return (    <Stack gap="related">      <RecurrenceField label="Backups run" dtstart="2026-11-02" value={rule} locale="en-US" />      <Tag>{rule.value}</Tag>    </Stack>  )}

Installation

npm install @weft-js/warp

Usage

tsx

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

Fewer choices

frequencies and preview trim the field.

tsx

import { RecurrenceField } from '@weft-js/warp'export function Limited() {  return (    <RecurrenceField label="Digest email" dtstart="2026-11-02" defaultValue="FREQ=DAILY" frequencies={[...DAILY_WEEKLY]} preview={3} locale="en-US" />  )}const DAILY_WEEKLY = ['DAILY', 'WEEKLY'] as const

A rule it can't edit

Parts it doesn't understand are never rewritten, so it shows the rule read-only.

tsx

import { RecurrenceField } from '@weft-js/warp'export function Custom() {  return (    <RecurrenceField label="Report" dtstart="2026-11-02" defaultValue="FREQ=MONTHLY;BYDAY=FR;BYSETPOS=-1;BYHOUR=9" locale="en-US" />  )}

In a settings card

Use dtstart for the first date and preview for how many coming dates to list.

tsx

import { state } from '@weft-js/core'import { Card, RecurrenceField, Stack, Text } from '@weft-js/warp'export function InCard() {  const rule = state<string | null>('FREQ=MONTHLY;BYMONTHDAY=1')  return (    <Card title="Rotate certificates">      <Stack gap="group">        <Text subtle>edge-cache renews its certificates on this schedule.</Text>        <RecurrenceField label="Repeats" dtstart="2026-12-01" value={rule} preview={3} locale="en-US" />      </Stack>    </Card>  )}

Accessibility

This has no shortcuts of its own: controls inside it use Tab, Enter and Space as usual, and warp's parts keep their roles and labels.

API Reference

Prop	Type	Default	Description
`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.
`label`	`string`	—	Its accessible name. Fields show it; icon-only controls speak it.
`dtstart`	`${number}-${number}-${number}`	—	The first date, which the next dates count from.
`preview`	`number`	`5`	How many next dates to list.
`frequencies`	`Frequency[]`	`FREQS`	Which of `DAILY`, `WEEKLY`, `MONTHLY`, `YEARLY` to offer.
`locale`	`string`	—	The language and region used to format values.
`name`	`string`	—	The name it posts under in a form.

Event	Type	Default	Description
`onValueChange`	`((v: string \| null, reason: ChangeReason) => void)`	—	Called with each new value, and whether a pointer, a key or code made the change.

RelatedCalendar Date field