Skip to main content
The Tax Form Runs page lists all tax form runs with filtering controls and provides dialogs to initiate new runs for each supported form type. It is served at route /hr/payroll/tax-forms/runs.

​
Overview

The page uses useTaxFormRuns with server-side filters for tax year, form type, status, and quarter. Filter controls are rendered above the run list. A “New Run” dropdown button opens the appropriate creation dialog based on form type:
  • CreateW2RunDialog — W-2
  • CreateQuarterlyRunDialog — quarterly forms (941, AZ-A1-QRT)
  • CreateAnnualRunDialog — annual forms (940, AZ-A1-R)
  • Create1099NECRunDialog — 1099-NEC
Each run card links to the run detail page. Supported form types and statuses are defined in TAX_FORM_TYPES, TAX_FORM_STATUSES, TAX_FORM_TYPE_LABELS, and TAX_FORM_STATUS_LABELS. No RequirePermission guard on this route (Tax Form Settings requires HR_PERMISSIONS.PAYROLL_ADMIN; confirm access controls with SME).

​
Who it’s for

Access follows your organization’s role and module configuration. SME: confirm whether hr.payroll.admin is required.

​
Before you start

  • Employer tax configuration must exist for the target tax year at /hr/payroll/tax-forms/settings.

​
Steps

View runs
  1. Navigate to HR > Payroll > Tax Forms > Runs or go to /hr/payroll/tax-forms/runs.
  2. Use the Year, Type, Status, and Quarter filters to narrow the list.
  3. Click a run card to open the detail page.
Create a new run
  1. Click the New Run dropdown (top right).
  2. Select the form type (W-2, Quarterly, Annual, 1099-NEC).
  3. Complete the creation dialog and confirm.

​
Key concepts

​
Viewing a tax form run

The Tax Form Run Details page manages a single tax form run through its lifecycle, from item generation to distribution or e-filing. It is served at route /hr/payroll/tax-forms/runs/:runId. The page loads run data via useTaxFormRunById, items via useTaxFormItems, and employer config via useEmployerTaxConfigByYear. It renders:
  • A status badge (TaxFormRunStatusBadge) and breadcrumb navigation.
  • FilingMethodRadio to select paper vs. e-file.
  • EFileStatusCard for e-file status and credential check.
  • W2PreviewCard for individual item previews.
  • Action buttons: generate items, finalize and distribute, delete run, create W-2 correction.
  • useGenerateW2Pdf for PDF download.
No RequirePermission guard is present on this specific route, but access should be limited to payroll administrators. The Tax Form Settings route (parent) requires HR_PERMISSIONS.PAYROLL_ADMIN (hr.payroll.admin). Confirm access controls with SME. Before you start: employer tax configuration for the relevant tax year must exist at /hr/payroll/tax-forms/settings. E-file credentials must be configured before e-filing is available.
  1. Navigate to HR > Payroll > Tax Forms > Runs and click a run, or go to /hr/payroll/tax-forms/runs/:runId.
  2. Review the run summary (form type, tax year, period, status).
  3. If items have not been generated, click the generate action to create tax form line items.
  4. Select the Filing Method (paper or e-file).
  5. Review items and preview W-2 PDFs as needed.
  6. When ready, use the Finalize & Distribute action to send forms.
  7. For corrections, use Create W-2 Correction.
Key detail concepts:

​
Generating a new hire report

The New Hire Report page at /hr/payroll/tax-forms/new-hire (NewHireReportPage, HR-PAY-04) supports state new hire reporting workflows. It lists recently hired employees within a configurable date range and allows administrators to select records and export them as a CSV file. Records can also be marked as reported after filing. By default the view shows unreported-only records; the date range defaults to the most recent 20 days. Key concepts:
  • Unreported — A new hire record that has not yet been marked as reported to the relevant state agency.
  • CSV Export — A comma-separated values file generated from the selected records for use in filing.
Before you start: ensure employee hire dates are accurately recorded in the system; determine the date range and reporting period required by the filing agency.
  1. Navigate to /hr/payroll/tax-forms/new-hire.
  2. Adjust the Start Date and End Date fields as needed.
  3. Use the Unreported only toggle to show or hide previously reported hires.
  4. Select the employee rows to include in the report.
  5. Click Download CSV to export the report file.
  6. After filing, mark the records as reported using the available action.

Human Resources

Human Resources core overview.

Governance & parity

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.
  • src/routes/hr.tsx
  • src/cores/hr/pages/TaxFormRunsPage.tsx
  • src/cores/hr/pages/TaxFormRunDetailPage.tsx
  • src/cores/hr/pages/NewHireReportPage.tsx
  • src/cores/hr/hooks/tax-forms/useTaxFormRuns.ts
  • src/cores/hr/hooks/tax-forms/useTaxFormItems.ts
  • src/cores/hr/hooks/tax-forms/useTaxFormRunMutation.ts
  • src/cores/hr/hooks/useNewHireReport.ts
  • src/cores/hr/services/new-hire.ts
  • src/cores/hr/types/tax-forms.ts