IncomeTab Documentation

The IncomeTab component allows users to manage their primary and additional income streams for financial planning. It provides a clear distinction between regular salary/wages and other forms of income, ensuring accurate tax and KiwiSaver calculations.

This tab controls:

Primary Incomes: Main and partner's regular income, including KiwiSaver contributions.
Additional Incomes: Other income sources like bonuses, rental income, or side hustles, with flexible tax and KiwiSaver options.

Inputs

Primary Incomes

These are the main sources of income for the individual and their partner. The primary incomes section is collapsible and its state.

Annual Income: The gross annual income before tax.
Employee KiwiSaver (%): The percentage of income the employee contributes to their KiwiSaver. Common rates are 3%, 4%, 6%, 8%, or 10%. Range: 0-100%, default: 3% - Change step of 0.5%
Employer KiwiSaver (%): The percentage of income the employer contributes to the employee's KiwiSaver. The minimum is typically 3%. Range: 0-100%, default: 3% - Change step of 0.5%
Start Age: The age at which this income stream begins. Range: 0-110, clamped on blur.
End Age: The age at which this income stream ends. Range: 0-110, clamped on blur, must not be less than Start Age.
Inflation Rate (%): The annual rate at which this income is expected to grow. This overrides the default inflation rate. Only visible when hideInflationInputs is false. Read-only in Real Values mode.

Additional Incomes

These are for any other income sources. Each additional income card is individually collapsible with state persisted in localStorage.

Description: A custom name for the income stream (e.g., "Rental Income", "Annual Bonus"). Editable inline in the card header.
Annual Income: The gross annual amount of the additional income.
Tax Type: Determines how the income is taxed and to whom it belongs.
- Main Income: Taxed as part of the main person's income. Automatically assigns to main member for KiwiSaver.
- Partner Income: Taxed as part of the partner's income. Automatically assigns to partner member for KiwiSaver.
- Tax Free: No tax is applied to this income. KiwiSaver contributions not applicable.
- Business Income: Income from business activities. KiwiSaver contributions not applicable.
Inflation Rate (%): The individual inflation rate for this income stream. Only visible when hideInflationInputs is false. Max: 20%, step: 0.5%. Read-only in Real Values mode.
Start Age: The age when this income begins. Range: 0-110, clamped on blur.
End Age: The age when this income ends. Range: 0-110, clamped on blur, must not be less than Start Age.
Employee KiwiSaver (%): The percentage of this income to contribute to KiwiSaver. Range: 0-100%, step: 0.5%, default: 3%. Only applicable and visible if the tax type is "Main Income" or "Partner Income".
Employer KiwiSaver (%): The employer's KiwiSaver contribution percentage for this income. Range: 0-100%, step: 0.5%, default: 3%. Only applicable and visible if the tax type is "Main Income" or "Partner Income".

Calculations

Income Inflation

Both primary and additional incomes are adjusted for inflation annually.

Formula: Inflated Income = Annual Income * (1 + Inflation Rate / 100) ^ (Current Age - Start Age)

Example:

Annual Income: $80,000
Inflation Rate: 3%
Start Age: 30
Current Age: 35

Inflated Income = $80,000 * (1 + 3 / 100) ^ (35 - 30) = $80,000 * 1.03 ^ 5 = $92,742

Real Values Mode: When realValuesMode is enabled, the component handles inflation differently:

Retrieves original inflation rates from inputData.original_inflation_rates JSONB field
If missing, reverse-calculates: Original Rate = Adjusted Rate + Global Inflation
Displays adjusted rate: Displayed Rate = Original Rate - Global Inflation

KiwiSaver Contributions

KiwiSaver contributions are calculated for each applicable income stream (main and partner incomes only).

Eligibility:

Primary incomes (main and partner) always have KiwiSaver contributions
Additional incomes only have KiwiSaver if tax_type is "main" or "partner"
Tax-free and business incomes do NOT have KiwiSaver contributions

Employee Contribution Formula: Employee Contribution = Inflated Income * (Employee KiwiSaver % / 100)

Employee contributions are deducted directly from gross income before PAYE tax.

Employer Contribution Formula (with ESCT): Employer contributions are subject to ESCT (Employer Superannuation Contribution Tax):

Gross Employer Contribution = Inflated Income * (Employer KiwiSaver % / 100)
ESCT Rate = calculateESCTRate(Total Annual Income)
ESCT Tax = Gross Employer Contribution * ESCT Rate
Net Employer Contribution = Gross Employer Contribution - ESCT Tax

ESCT Rates (Effective 1 April 2025): ESCT uses a single rate for the entire contribution based on the employee's annual income:

| Annual Income Range | ESCT Rate | | ------------------- | --------- | | $0 - $18,720 | 10.5% | | $18,721 - $64,200 | 17.5% | | $64,201 - $93,720 | 30% | | $93,721 - $216,000 | 33% | | Over $216,000 | 39% |

Important Notes:

ESCT is calculated based on the employee's total annual income (not just the income stream)
For additional incomes, ESCT rate is calculated using: Main Income + Additional Income (or Partner Income + Additional Income)
Unlike progressive tax, ESCT applies a single flat rate to the entire employer contribution
The net employer contribution (after ESCT) is what gets deposited into the KiwiSaver account

Example:

Inflated Income: $100,000
Employee KiwiSaver: 3%
Employer KiwiSaver: 3%

Employee Contribution = $100,000 * 3% = $3,000

Gross Employer Contribution = $100,000 * 3% = $3,000
ESCT Rate (for $100,000 income) = 33%
ESCT Tax = $3,000 * 33% = $990
Net Employer Contribution = $3,000 - $990 = $2,010

Total Annual KiwiSaver Contribution = $3,000 + $2,010 = $5,010

Contribution Timing: The financial model applies KiwiSaver contributions at the beginning of each year, not the end. This means:

Each contribution earns investment returns for a full year before the next contribution
This is more favorable than end-of-year contributions (standard formula assumption)
Mathematically equivalent to: Standard FV × (1 + Return Rate)
Example: A 35-year projection with 3.5% returns would yield ~3.5% more than standard end-of-year formulas

This beginning-of-year methodology is more conservative and favorable for retirement planning purposes.

Total Taxable Income

The total taxable income is the sum of all income streams that are not marked as "Tax Free".

Formula: Total Taxable Income (Main) = Primary Main Income + Sum of Additional Incomes (Tax Type: Main) Total Taxable Income (Partner) = Primary Partner Income + Sum of Additional Incomes (Tax Type: Partner) Total Taxable Income (Business) = Sum of Additional Incomes (Tax Type: Business)

Note: Tax-free incomes are excluded from taxable income calculations.

UI Features

Layout Modes

The component supports multiple layout modes:

Normal View (isSidebarView = false):

Primary incomes displayed in 2-column grid (side-by-side for main and partner)
Default layout: 3x2 grid (3 columns, 2 rows) for all fields
When hideInflationInputs = true: 2-row layout with adjusted column spans

Sidebar View (isSidebarView = true):

All incomes displayed in single-column vertical layout
Optimized for narrow sidebar panels
6-row grid for primary incomes (one field per row)

Validation & Input Handling

Age Clamping:

All age inputs clamped to 0-110 range on blur
End age automatically adjusted if set below start age
Prevents invalid age ranges

Inflation Rate Syncing: When hideInflationInputs = true:

Individual inflation inputs are hidden from UI
All income inflation rates automatically sync with global inputData.inflation_rate
Changes to global rate propagate to all incomes

Member Assignment:

Automatically set when tax_type changes
tax_type = 'main' → member_assignment = 'main'
tax_type = 'partner' → member_assignment = 'partner'
tax_type = 'tax_free' | 'business' → member_assignment = 'none'
KiwiSaver fields appear/disappear based on member assignment

Wealthie Documentation

Documentation