lohnsteuerrechner

German wage tax calculation from the official BMF Programmablaufplan.

Published on npm as lohnsteuerrechner.

Live Demo

Installation

npm install lohnsteuerrechner

Features

• Official BMF PAP implementation for 2025 and 2026
• Cent-exact results aligned with the BMF Steuerrechner API
• Supports all 6 tax classes and all 4 pay periods
• Computes Solidaritaetszuschlag and church tax bases
• Handles supplementary payments (sonstige Bezuege)
• Includes pension and age-related allowance rules from PAP
• Uses Decimal arithmetic (decimal.js) to avoid floating-point rounding errors
• Framework-agnostic core for Node.js and browsers

Quick Start

import { calculate } from "lohnsteuerrechner";

const result = calculate(2026, { LZZ: 2, RE4: 500000, STKL: 1, KVZ: 2.5, PVZ: 1 });

console.log(result.LSTLZZ); // 78583 (Cent = 785.83 EUR)
console.log(result.SOLZLZZ); // 0

React Headless Component

import { LohnsteuerRechner } from "lohnsteuerrechner/react";

export function PayrollForm() {
  return (
    <LohnsteuerRechner year={2026} inputs={{ LZZ: 2, RE4: 500000, STKL: 1 }}>
      {({ getSelectInputProps, getNumberInputProps, getCheckboxInputProps, outputs }) => (
        <div>
          <select {...getSelectInputProps("LZZ")}>
            <option value="1">Year</option>
            <option value="2">Month</option>
            <option value="3">Week</option>
            <option value="4">Day</option>
          </select>

          <input type="number" {...getNumberInputProps("RE4")} />
          <select {...getSelectInputProps("STKL")}>...</select>
          <input type="number" step="0.01" {...getNumberInputProps("KVZ")} />
          <input type="checkbox" {...getCheckboxInputProps("PVZ")} />

          <output>{outputs?.LSTLZZ ?? 0}</output>
        </div>
      )}
    </LohnsteuerRechner>
  );
}

API Reference

calculate(year, inputs)

function calculate(year: number, inputs: LohnsteuerInputs): LohnsteuerOutputs;

• year: currently supported 2025 | 2026
• inputs: PAP input parameters (all monetary values in Cent at the API boundary)
• returns all PAP output values as integers in Cent

SUPPORTED_YEARS is also exported from the package entrypoint.

LohnsteuerInputs

All input fields are optional; omitted values fall back to PAP defaults.

Core

| Field | Type | Description | | --- | --- | --- | | LZZ | number | Pay period: 1=year, 2=month, 3=week, 4=day | | RE4 | number | Taxable gross wage for the pay period (Cent) | | STKL | number | Tax class (1..6) | | R | number | Religious affiliation marker (0 if none) | | ZKF | number | Child allowance factor (1 decimal place) |

Insurance

| Field | Type | Description | | --- | --- | --- | | KRV | number | Pension insurance marker | | ALV | number | Unemployment insurance marker | | PKV | number | Health insurance marker (0 public, 1 private) | | KVZ | number | Additional health insurance contribution rate in percent | | PVZ | number | Pflegeversicherung surcharge for childless employees | | PVS | number | Saxony Pflegeversicherung special rule marker | | PVA | number | Number of child-based Pflegeversicherung deductions (0..4) | | PKPV | number | Private health/care insurance monthly amount (Cent) | | PKPVAGZ | number | Employer subsidy for private insurance monthly amount (Cent) |

Pension and Age Relief

| Field | Type | Description | | --- | --- | --- | | VBEZ | number | Pension benefits included in RE4 (Cent) | | VBEZM | number | Monthly pension amount for reference month (Cent) | | VBEZS | number | Expected pension special payments in start year (Cent) | | VBS | number | Pension benefits included in SONSTB (Cent) | | VJAHR | number | Year pension payments started | | ZMVB | number | Number of pension months (annual calculation) | | ALTER1 | number | Age relief marker (1 if eligible) | | AJAHR | number | Year following 64th birthday |

Allowances and Additions

| Field | Type | Description | | --- | --- | --- | | LZZFREIB | number | Pay-period tax-free allowance (Cent) | | LZZHINZU | number | Pay-period addition amount (Cent) | | JFREIB | number | Annual allowance for supplementary payments (Cent) | | JHINZU | number | Annual addition for supplementary payments (Cent) |

Supplementary Payments

| Field | Type | Description | | --- | --- | --- | | SONSTB | number | Supplementary payments (Cent) | | SONSTENT | number | Compensation amounts within SONSTB (Cent) | | STERBE | number | Death benefit amount within SONSTB (Cent) | | JRE4 | number | Expected annual wage for supplementary calculations (Cent) | | JRE4ENT | number | Compensation amounts within JRE4 (Cent) | | JVBEZ | number | Pension benefits included in JRE4 (Cent) | | MBV | number | Non-taxable stock participation benefits (Cent) |

Factor Method (Tax Class IV)

| Field | Type | Description | | --- | --- | --- | | af | number | Factor method marker (0/1, default 1) | | f | number | Factor value with 3 decimal places |

LohnsteuerOutputs

All output fields are integer Cent values.

| Field | Description | | --- | --- | | LSTLZZ | Wage tax for the pay period | | SOLZLZZ | Solidarity surcharge for the pay period | | STS | Wage tax for supplementary payments | | SOLZS | Solidarity surcharge for supplementary payments | | BK | Church tax base | | BKS | Church tax base for supplementary payments | | VFRB | Used allowance (DBA output) | | VFRBS1 | Used allowance for expected annual wage (DBA output) | | VFRBS2 | Used allowance for supplementary payments (DBA output) | | WVFRB | Available taxable income above basic allowance (DBA output) | | WVFRBO | Available taxable income above basic allowance for expected wage (DBA output) | | WVFRBM | Available taxable income above basic allowance for supplementary payments (DBA output) |

Supported Years

| Year | PAP XML Source | Status | | --- | --- | --- | | 2025 | Lohnsteuer2025.xml | Implemented | | 2026 | Lohnsteuer2026.xml | Implemented |

Yearly Update Quickstart

To implement a new PAP year with the update agent:

npm run update-pap

Equivalent direct command:

npx opencode-ai run --command project:update-pap

The full workflow spec lives in .opencode/commands/update-pap.md.

Validation

• 2026 implementation is validated against the official BMF external API with cached fixture vectors.
• Known example:
  • Inputs: LZZ=2, RE4=500000, STKL=1, KVZ=2.50, PVZ=1
  • Output: LSTLZZ=78583, SOLZLZZ=0
• Official BMF interface: https://www.bmf-steuerrechner.de/interface/2026Version1.xhtml?code=LSt2026ext

Vanilla JS / CDN

Use directly in the browser with jsDelivr:

<script type="module">
  import { calculate } from "https://cdn.jsdelivr.net/npm/lohnsteuerrechner/+esm";

  const result = calculate(2026, { LZZ: 2, RE4: 500000, STKL: 1, KVZ: 2.5, PVZ: 1 });
  console.log(result.LSTLZZ);
</script>

License

MIT