# payroll.holiday-entitlement
Statutory annual leave in Great Britain under the Working Time Regulations 1998
(WTR). The regulations sort workers into two groups, and so does this
function's `kind`.
## Regular workers (`regular`)
Regulations 13 and 13A: 4 weeks plus 1.6 weeks, so **5.6 weeks of the days the
worker works**, with a **maximum of 28 days**. Five days a week is exactly 28
days; six days a week would be 33.6 and is capped to 28 (`capped` is true);
2.5 days a week is 14 days.
Days a week is given in hundredths (`daysPerWeekX100`, 250 = 2.5 days) and the
answer is in hundredths of a day (`daysX100`), so part-time patterns are exact.
When employment starts or ends inside the leave year, the worker gets the
proportion of the (capped) entitlement that matches the part of the leave year
they are employed: days employed over days in the leave year, both ends
inclusive (regs 13(5) and 13A(5) for starters; reg 14 uses the same
proportion for leavers). The result is **rounded up** to the next hundredth of
a day, because an employer may round a worker's leave up but never down. The
leave year is 12 calendar months from `leaveYearStart`, so a leave year
containing 29 February has 366 days.
Employers often use GOV.UK's simpler monthly accrual for a first year (one
twelfth a month, rounded up to the next half day). That is a permitted
alternative, not the statutory proportion, and is not what this returns.
## Irregular-hours and part-year workers (`irregular-hours`, `part-year`)
For **leave years beginning on or after 1 April 2024**, regulation 15B: on the
last day of each pay period the worker accrues **12.07% of the hours worked in
that period**. A fraction of an hour under 30 minutes counts as nothing; 30
minutes or more counts as a whole hour (reg 15B(5)). 30 hours worked accrues
3.621 hours, so 4 hours, which is GOV.UK's own example. The answer is whole
hours for the pay period (`hoursAccrued`); keep the running balance yourself.
For an irregular-hours worker in a leave year that began before 1 April 2024
this refuses to answer: those years use the 5.6-week rule, averaged over a
reference period, which needs a history this function does not take.
Not modelled for accrual workers: the 28-day annual ceiling (reg 15B(4)),
which needs the employer's length of a day to convert into hours, and accrual
during sick or statutory leave (reg 15C). Both are the caller's.
The weeks, the 28-day cap, the 12.07% and the 1 April 2024 start are dated
rows in `data/holiday-rules.json`.
## Sources
- The Working Time Regulations 1998 (SI 1998/1833), regs 13, 13A, 15B and 15C
as amended from 1 January 2024 by SI 2023/1426:
https://www.legislation.gov.uk/uksi/1998/1833/regulation/13,
https://www.legislation.gov.uk/uksi/1998/1833/regulation/13A,
https://www.legislation.gov.uk/uksi/1998/1833/regulation/15B
- The Employment Rights (Amendment, Revocation and Transitional Provision)
Regulations 2023 (SI 2023/1426): https://www.legislation.gov.uk/uksi/2023/1426/made
- GOV.UK, "Holiday entitlement: calculate leave entitlement" (12.07% of hours in
the pay period, rounded to the nearest hour at 0.5; the 30-hour example; the
1 April 2024 start): https://www.gov.uk/holiday-entitlement-rights/calculate-leave-entitlement
## Before you rely on this
**Not professional advice.** This capability calculates payroll figures from published rules. It is a software component for developers, not tax or legal advice. Rules change and every rate here has an effective date. Check that the dates cover your case. Verify results against the official sources listed above, and have a payroll specialist review how you use it, before anyone relies on the output. Provided "as is" under its licence, without warranty.
**Unreviewed.** This capability's implementations agree in every language and pass its published test vectors, which were worked out from the official sources cited. But no qualified payroll specialist has yet checked those vectors, or confirmed that the capability covers the cases it claims. Treat it as a draft. Do not use it for real people, money or decisions without your own expert review. Once a qualified reviewer signs off, this notice is replaced with their name, qualification and the date. Each new version needs fresh sign-off.
## Notices
Contains public sector information licensed under the Open Government
Licence v3.0 (https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/).
Legislation: Crown copyright and database right.
1.0.1 marks it unreviewed and adds its attribution notices (NOTICE). The code and the tests are unchanged.