Introduction

recurring-dates is a tiny toolkit for generating recurring date schedules. It ships a pure Vanilla JS function and a React hook, so it fits any JavaScript project.

Key Philosophy

One function, one config object, every recurrence pattern you need. Daily, weekly, monthly, and yearly — with ordinals, weekday filters, custom intervals, explicit exclusions, and configurable date formats.

Features

Daily, weekly, monthly, yearly frequencies

Custom intervals (every N days/weeks/months/years)

Weekday selection (MON–SUN)

Ordinal week support (FIRST–FIFTH, LAST)

Month name selection (JAN–DEC)

Specific day-of-month selection (1–31)

Date exclusion list

Configurable date format

Human-readable text output

Input validation with error messages

React hook (useRecurringDates)

UMD bundle for CDN usage

Exported APIs

generateRecurringDates(config)

Core function. Returns { text, dates } or { dates: [], error } on validation failure.

getRecurringDates(config)

Shorthand alias that always returns an object (never undefined).

useRecurringDates(config)

React hook that memoises the result. Re-computes when config changes.

Quick Example

Quick Start

import { generateRecurringDates } from "recurring-dates";

const { text, dates } = generateRecurringDates({
  STARTS_ON: "01-01-2025",
  ENDS_ON: "31-01-2025",
  FREQUENCY: "W",
  WEEK_DAYS: ["MON", "THU"],
  EXCLUDE_DATES: ["13-01-2025"],
});

console.log(text);  // "Every week on Monday and Thursday"
console.log(dates); // ["02-01-2025", "06-01-2025", ...]