# Recurrence editor

A React component in [Beamline](https://beamline.io/)'s [Form controls](https://beamline.io/components/forms) category. Live demo: https://beamline.io/components/recurrence-editor

How something repeats, set in plain controls and said back in a sentence: every N days, weeks, months or years; which weekdays; in a month, on a date or on the second Tuesday (or the last Friday); ending never, on a date or after a number of times. The next dates are listed so the rule can be checked against a calendar, months without the chosen date are said, and the rule comes out as a value and an iCalendar RRULE.

## Use it for

- Repeating events, reminders, reports, invoices, payouts or maintenance windows: the person sets how often and until when.
- Anywhere an RRULE (RFC 5545) is stored and has to be readable by people.

## Not for

- One date or time ([date-picker](https://beamline.io/components/date-picker), [time-picker](https://beamline.io/components/time-picker)).
- Opening hours or when someone can be booked ([availability-rule-editor](https://beamline.io/components/availability-rule-editor)).
- A range of dates ([date-range-picker](https://beamline.io/components/date-range-picker)).

## Anatomy

- summary: the rule in one sentence ('Every 2 weeks on Monday and Thursday, until 31 Dec 2026') that wraps in a narrow room and fades to its next wording as the rule changes
- frequency: Daily, Weekly, Monthly, Yearly
- interval: 'Every [n] weeks' (the unit follows the frequency and its count)
- weekly: the seven weekdays as toggles, the start's weekday on by default; at least one stays on
- monthly: on day 15, or on the second Tuesday (first, second, third, fourth, last), both read from the start date
- ends: never, on a date, or after n times
- a note when a monthly date does not exist in every month (the 31st): those months are skipped
- next dates: the next five, from the start

## Variants

- **frequencies**: daily, weekly, monthly, yearly

## States

- daily
- weekly
- monthly by date
- monthly by weekday
- yearly
- ends never
- ends on a date
- ends after n
- skipped months
- an end before the start (said, no dates listed)
- disabled

## Keyboard

- Each control is the system's own: the segmented frequency and the weekday toggles move with ← →, the number fields step with ↑ ↓, the radio groups with the arrow keys
- The summary is a live line for assistive tech: the sentence is read after a change settles

## Motion

Controls that belong to one frequency grow in and out as it changes (the panel eases to its height); the summary fades to its next sentence (a sentence wraps, so it is not morphed letter by letter); the next dates keep their path: dates that remain slide to their new place, new ones arrive, old ones leave. Reduced motion: changes are instant.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `start` (required) | `Date` | — | The first time it happens; the defaults (weekday, day of month) are read from it. |
| `value / defaultValue / onValueChange` | `Recurrence` | — |  |
| `preview` | `number` | — | How many next dates to list. Default 5; 0 hides the list. |
| `frequencies` | `RecurrenceFrequency[]` | — | Which to offer. Default all four. |
| `weekStartsOn` | `0 \| 1` | — | Order of the weekday toggles. Default 1 (Monday). |
| `locale` | `string` | — | Dates in the summary and the list. Default en-US. |
| `disabled` | `boolean` | — |  |
| `className / classNames / style / ref` | `root` | — |  |

## Built from

- [segmented-control](https://beamline.io/components/segmented-control)
- [number-field](https://beamline.io/components/number-field)
- [toggle-group](https://beamline.io/components/toggle-group)
- [radio-group](https://beamline.io/components/radio-group)
- [date-picker](https://beamline.io/components/date-picker)

## Dependencies

`@radix-ui/react-toggle-group`, `@radix-ui/react-radio-group`

## Import

```tsx
import { RecurrenceEditor } from "@/components/recurrence-editor/recurrence-editor";
```

## Get it

Recurrence editor is part of Beamline: 200+ components and 50+ complete screens for React that your coding agent (Claude Code, Codex, Cursor or any MCP client) installs into your app through Beamline's MCP server, as a ready-built package or as plain React source you can change. $49 launch price, one payment, no subscription, lifetime updates, one licence for your whole team. [Get Beamline](https://beamline.io/checkout?pack=complete) · [Connect your agent](https://beamline.io/connect)

## More in Form controls

- [Color Palette](https://beamline.io/components/color-palette): A wheel of preset colours to pick from: twelve hues around the ring, their tints inward, white at the middle; the chosen swatch lifts and carries a check.
- [Rich text editor](https://beamline.io/components/rich-text-editor): A Notion-grade writing surface: slash menu for every block, a formatting toolbar on selection, drag-to-move blocks, nesting, markdown shortcuts, paste…
- [Allocation editor](https://beamline.io/components/allocation-editor): Parts of a fixed whole edited as transfers: an ordered strip whose boundaries drag or step between neighbours and a roster of exact amounts where typing…
- [Radio cards](https://beamline.io/components/radio-cards): One choice among rich options as cards with optional media, icon, detail and a figure; one selection ring follows the stable choice.
- [Calendar](https://beamline.io/components/calendar): Month grids for picking a day or a range: a real grid with arrows by day and week, Page keys by month, closed days, today's dot, and a range span that…
- [Availability rule editor](https://beamline.io/components/availability-rule-editor): When someone (or something) can be booked: hours for each day of the week, one or more ranges a day, a day turned off, a day's hours copied to the others…
- [Signature pad](https://beamline.io/components/signature-pad): A pad for a drawn signature whose ink follows a stylus's pressure (and thins with speed under a mouse or finger); undo, replay, PNG or SVG export, and…
- [Image cropper](https://beamline.io/components/image-cropper): Frame a picture before it is saved: a fixed window (square, round for avatars, wide for covers, or free with handles) over the picture, which you drag…
- [Input Dissolve](https://beamline.io/components/input-dissolve): A one-line field whose text breaks into specks and drifts off once it is sent, last letter first; the field is empty and ready again.
- [Password field](https://beamline.io/components/password-field): A password field with a reveal control, and a strength meter when a password is being created.
- [Card field](https://beamline.io/components/card-field): A payment card in one field: the number groups as it is typed and names its network, the expiry and security code follow on their own as each part…
- [File drop zone](https://beamline.io/components/file-dropzone): A generous target for files: drop or choose, each checked against type, size and count with the reason when turned away; uploads show progress and can be…
- [Slider](https://beamline.io/components/slider): A value or range on a known scale: the thumb grows under the finger and shows its value while dragged or focused; marks, end icons and a value readout.
- [Rating](https://beamline.io/components/rating): A score on a small scale: stars that fill as you point (halves too) and light one after another when chosen, with the word for the score beside them…
- [Date range picker](https://beamline.io/components/date-range-picker): A reporting range: presets on one side and two months on the other (one on a phone); the trigger names the preset in use, and the footer counts the days.
- [OTP input](https://beamline.io/components/otp-input): A verification code in separate boxes backed by one real field, so paste, SMS autofill and Backspace work; optional groups like 123–456.
- [Segmented control](https://beamline.io/components/segmented-control): Two to five views or ranges of the same content (1D / 1W / 1M, List / Board): a radio group whose raised thumb slides to the choice.
- [Colour picker](https://beamline.io/components/color-picker): A swatch that opens a picker: saturation-brightness plane, hue strip, HEX/RGB/HSL/OKLCH value to type or copy, the screen eyedropper where available…
- [Chip group](https://beamline.io/components/chip-group): Quick filters as chips: a chosen chip fills and grows a check, counts show what each would return, and extra chips fold behind “+N”.
- [Shortcut recorder](https://beamline.io/components/shortcut-recorder): Lets people set their own shortcut: press the keys, see them as keycaps; a clash or a browser-kept shortcut asks first. ShortcutCheatsheet lists every…
- [Mention input](https://beamline.io/components/mention-input): A composer where @people and #channels become single tokens with suggestions at the caret; the value keeps the text and where each mention sits.
- [Tag input](https://beamline.io/components/tag-input): Short free-form values as tags: Enter, comma or Tab adds, a pasted list adds them all, Backspace twice removes the last; duplicates and invalid values…
- [Multi-select](https://beamline.io/components/multi-select): Several values from a known list as removable chips in the field; the list has a search field (for long lists), checkable rows and a count with Clear.
- [Tree select](https://beamline.io/components/tree-select): A field that picks from a tree: departments and teams, categories and subcategories, folders, regions and cities; the list opens as an indented tree…
- [Combobox](https://beamline.io/components/combobox): One value from a long list found by typing (time zones, countries, customers): ranked matches with the match emphasised, keywords, optional group…
- [Phone input](https://beamline.io/components/phone-input): A phone number with its country: searchable picker with country and dialling codes, “+44…” switches the country, the number groups as typed, and the…
- [Date picker](https://beamline.io/components/date-picker): One date in a form: a field that opens the month grid under it with focus inside, picks and closes; Today and Clear below, optional clear button.
- [Time picker](https://beamline.io/components/time-picker): A time of day as hour and minute segments, typed or stepped, 12- or 24-hour; the clock opens a list of times at the step.
- [Number field](https://beamline.io/components/number-field): A bounded number with − and +: arrows and Page keys step, typing is read in the locale and clamped on leaving, limits can be explained, and the label can…
- [Inline edit](https://beamline.io/components/inline-edit): Text that becomes a field in the same place: Enter (or ⌘Enter when multiline) saves, Escape cancels, leaving saves; saving shows progress and a refusal…
- [Search field](https://beamline.io/components/search-field): The search entry point: magnifier, clear button, Escape to clear, a shortcut hint and an optional live border beam.
- [Switch](https://beamline.io/components/switch): A setting that applies at once: a thumb that slides on a spring and stretches under the finger, with an optional label before or after.
- [Form](https://beamline.io/components/form): Validation wiring for react-hook-form (and zod) on the system's own fields: each field already links its label, help and error, so FormField hands over…
- [Select](https://beamline.io/components/select): One choice from a short known list, in the same frame as every text field: label, help, error, option groups and details.
- [Toggle group](https://beamline.io/components/toggle-group): Pressable toggles where one or several can be on: alignment, bold and italic, view options; bare for toolbars or framed.
- [Input](https://beamline.io/components/input): A single-line text field with its label, help and error wired for assistive tech, three sizes and adornments.
- [Checkbox](https://beamline.io/components/checkbox): A yes/no choice with an optional label and help, including the mixed state for select-all; the check draws itself in.
- [Radio group](https://beamline.io/components/radio-group): One choice from a short visible set, each option with an optional description, vertical or in a row.
- [Textarea](https://beamline.io/components/textarea): Multi-line plain text that grows with what is typed up to a limit, with an optional character count.
- [Label](https://beamline.io/components/label): The text label tied to a form control, with a required marker that screen readers announce.