Quick Start

Get up and running in under a minute. Here are the most common patterns.

1. Basic Daily Schedule

Generate every day between two dates:

Daily

import { generateRecurringDates } from "recurring-dates";

const result = generateRecurringDates({
  STARTS_ON: "01-01-2025",
  ENDS_ON: "07-01-2025",
  FREQUENCY: "D",
});

console.log(result.text);
// "Every day"

console.log(result.dates);
// ["01-01-2025", "02-01-2025", ..., "07-01-2025"]

2. Weekly on Specific Days

Pick which weekdays to include:

Weekly

const result = generateRecurringDates({
  STARTS_ON: "01-01-2025",
  ENDS_ON: "31-01-2025",
  FREQUENCY: "W",
  WEEK_DAYS: ["MON", "WED", "FRI"],
});

console.log(result.text);
// "Every week on Monday, Wednesday and Friday"

3. Monthly Pay Days

Select specific dates of each month:

Monthly

const result = generateRecurringDates({
  STARTS_ON: "01-01-2025",
  ENDS_ON: "31-12-2025",
  FREQUENCY: "M",
  MONTH_DATES: [1, 15],
});

console.log(result.text);
// "Every month on 1st and 15th"

4. React Hook Usage

Use the memoised hook in a component:

React Hook

import { useRecurringDates } from "recurring-dates";

function Schedule() {
  const { text, dates } = useRecurringDates({
    STARTS_ON: "2025-01-01",
    ENDS_ON: "2025-06-30",
    FREQUENCY: "M",
    MONTH_DATES: [1, 15],
    FORMAT: "YYYY-MM-DD",
  });

  return (
    <div>
      <h2>{text}</h2>
      <ul>
        {dates.map((d) => (
          <li key={d}>{d}</li>
        ))}
      </ul>
    </div>
  );
}

5. With Exclusions

Drop specific dates from the output:

Exclusions

const result = generateRecurringDates({
  STARTS_ON: "01-01-2025",
  ENDS_ON: "31-01-2025",
  FREQUENCY: "W",
  WEEK_DAYS: ["MON"],
  EXCLUDE_DATES: ["06-01-2025", "20-01-2025"],
});

// 06-01-2025 and 20-01-2025 will NOT appear in result.dates

Next Steps

Explore the Config Reference for all available options, or dive into the Yearly Frequency Guide for complex ordinal patterns.