> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# W-2 Forms

> List, view, and manage W-2 wage statement records for employees including box breakdown, distribution, and corrected W-2C creation.

The W-2 Forms page (`/fa/tax/forms/w2`) lists all W-2 wage statement records for the organization and provides navigation to individual form details.

## Overview

The W-2 Forms page renders a `DataTable` of `fa_w2_forms` rows via `useW2FormsList`. Columns include: Employee Name, Employee ID, Wages (`wages_tips_compensation` formatted as currency), Status, and a View action.

Clicking an employee name or View navigates to `/fa/tax/forms/w2/:id`. A **New** button is present in the header. The route is gated by `fa.tax.view`.

## Who it's for

Requires permission: `fa.tax.view`.

## Before you start

* W-2 records must be generated or imported.
* You need `fa.tax.view` to access this page.

## Steps

**View W-2 forms**

1. Navigate to `/fa/tax/forms/w2`.
2. Browse the data table.

**Open a specific W-2**

1. Click the Employee Name link or the **View** button.
2. The W-2 Form Details page opens at `/fa/tax/forms/w2/:id`.

## Key concepts

* **W-2 form**: A `fa_w2_forms` row with `employee_name`, `employee_id`, `wages_tips_compensation`, and `status`.

## Viewing a W-2 form

The W-2 Form Details page (`/fa/tax/forms/w2/:id`) shows the complete W-2 wage statement for a single employee and supports distribution and correction actions. Requires `fa.tax.view`.

The page loads a form via `useW2FormDetail` (keyed by `:id` and org) backed by the `fa_w2_forms` table. The breadcrumb label is derived from `employee_name`.

The page shows:

* A `W2BoxBreakdown` component rendering key-value pairs from the `box_amounts` JSON field (filtering out null/zero/empty values).
* A distribution action via `CreateDistributionDialog` (gated by `PermissionGate`).
* A **Create W-2C** (corrected W-2) button that calls `useCreateW2Form` with a corrected form payload.

Key concepts:

* **Box amounts**: JSON field (`box_amounts`) on `fa_w2_forms` containing per-box wage/tax values; rendered by `W2BoxBreakdown`.
* **W-2C**: A corrected W-2 form; created by calling `useCreateW2Form` with the same `tax_year_id` and corrected flag.

**View W-2 details:**

1. Navigate to `/fa/tax/forms/w2/:id` (or click a form from the W-2 Forms list).
2. Review the employee wage information and box breakdown.

**Initiate distribution:**

1. Click the distribution action (requires appropriate permission via `PermissionGate`).
2. Complete the `CreateDistributionDialog`.

**Create a corrected W-2 (W-2C):**

1. Click **Create W-2C**.
2. A corrected form is created via `useCreateW2Form`.

## Related

<Columns cols={2}>
  <Card title="Finance & Revenue" icon="building-columns" href="/fa/overview">
    Finance & Revenue core overview.
  </Card>

  <Card title="Governance & parity" icon="scale-balanced" href="/governance/index" />
</Columns>

<Note>
  This page documents shipped product behavior. It is not medical, legal, or
  billing advice. Verify against your organization's policies and applicable
  regulations before using it for clinical, compliance, or billing decisions.
  Protected health information (PHI) shown in the product is governed by your
  tenant's access controls and is never exposed in this documentation.
</Note>

<Accordion title="Documentation sources">
  * src/routes/fa.tsx
  * src/cores/fa/pages/W2FormsPage.tsx
  * src/cores/fa/pages/W2FormDetailPage.tsx
  * src/cores/fa/hooks/useW2Forms.ts
  * src/cores/fa/components/CreateDistributionDialog.tsx
  * src/cores/fa/types/tax.ts
</Accordion>