RecurrenceField

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

SourcePackage @kerf-js/veneer

Preview

tsx

import { state } from '@kerf-js/core'import {  RecurrenceField,  Stack,  Tag} from '@kerf-js/veneer'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 @kerf-js/veneer

Usage

tsx

import { RecurrenceField } from '@kerf-js/veneer'

Fewer choices

frequencies and preview trim the field.

tsx

import { RecurrenceField } from '@kerf-js/veneer'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 '@kerf-js/veneer'export function Custom() {  return (  <RecurrenceField    label="Report"    dtstart="2026-11-02"    defaultValue={schedule}    locale="en-US"  />  )}const schedule =  'FREQ=MONTHLY;BYDAY=FR;BYSETPOS=-1;BYHOUR=9'

In a settings card

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

tsx

import { state } from '@kerf-js/core'import {  Card,  RecurrenceField,  Stack,  Text} from '@kerf-js/veneer'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 veneer'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