The base date as a Date object or timestamp (number)
The number of years to subtract (can be negative to add)
A new Date object with the years subtracted, or Invalid Date if any input is invalid
// Subtract positive years
const result = subYears(new Date(2020, 0, 15), 3);
// Returns: 2017-01-15
// Add years (negative amount)
const result = subYears(new Date(2020, 0, 15), -3);
// Returns: 2023-01-15
// Fractional amounts are truncated
const result = subYears(new Date(2020, 0, 1), 1.9);
// Returns: 2019-01-01 (1.9 truncated to 1)
// Leap year to non-leap year (Feb 29 → Feb 28)
const result = subYears(new Date(2024, 1, 29), 1);
// Returns: 2023-02-28 (2023 is not a leap year)
// Leap year to leap year (Feb 29 → Feb 29)
const result = subYears(new Date(2024, 1, 29), 4);
// Returns: 2020-02-29 (2020 is a leap year)
// Invalid inputs return Invalid Date
const result = subYears(new Date("invalid"), 3);
// Returns: Invalid Date
Subtract the specified number of years from the given date.
This function validates arguments before processing and returns a new Date instance with the specified number of years subtracted. Fractional years are truncated toward zero. Preserves month, day, and time components. When the source date is Feb 29 and the target year is not a leap year, the result becomes Feb 28.