> ## 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.

# Benefit Plans

> Admin list of all benefit plans with type filtering and active/inactive toggling.

Benefit Plans is available at route `/hr/benefits/plans`, guarded by `hr.benefits.admin`.

## Overview

The Benefit Plans List page shows all benefit plans filterable by plan type via tab filters (Health, Dental, Vision, Retirement, Life, Disability, HSA, FSA, or All). Each plan is displayed in a data table with plan name, type badge, effective/expiry dates, and an actions dropdown providing View, Edit, and Toggle Active options. Active and inactive plan counts are tracked separately. A **New Plan** button navigates to `/hr/benefits/plans/new`.

## Who it's for

`hr.benefits.admin` — HR benefits administrators only.

## Before you start

* `hr.benefits.admin` permission required.

## Steps

<Steps>
  <Step title="Open Benefit Plans">Navigate to `/hr/benefits/plans`.</Step>
  <Step title="Filter by type">Click a plan type tab to show only plans of that category.</Step>
  <Step title="Act on a plan">Use the row actions dropdown to view details, edit, or toggle active status.</Step>
  <Step title="Create a plan">Click **New Plan** to navigate to the plan creation form.</Step>
</Steps>

## Key concepts

| Term              | Meaning in code                                                                |
| ----------------- | ------------------------------------------------------------------------------ |
| `BenefitPlanType` | `health`, `dental`, `vision`, `retirement`, `life`, `disability`, `hsa`, `fsa` |
| `is_active`       | Flag controlling whether a plan appears in enrollment workflows                |

## Viewing a benefit plan

The Plan Details page at `/hr/benefits/plans/:id` shows the full record for a single benefit plan in a tabbed interface. (Note: `/hr/succession/plans/:id` is a separate Succession Plan Detail page and not described here.)

The page loads a plan by its `:id`. It shows plan name, type (`health`, `dental`, `vision`, `retirement`, `life`, `disability`, `hsa`, `fsa`), and status badge. Four tabs provide: **Details** (plan metadata and cost information), **Coverage** (coverage level tiers and amounts), **Eligibility** (eligibility rules via `EligibilityRulesManager`), and **Enrollments** (employees currently enrolled). An Edit button is available for plan managers.

Requires `hr.benefits.admin` permission.

| Term             | Meaning                                                                  |
| ---------------- | ------------------------------------------------------------------------ |
| Coverage Level   | A tier within the plan (e.g., employee-only, employee + spouse, family). |
| Eligibility Rule | A condition that determines which employees may enroll in the plan.      |
| HSA / FSA        | Health Savings Account / Flexible Spending Account plan types.           |

1. Navigate to **HR → Benefits → Plans** (`/hr/benefits/plans`) and click a plan name.
2. Use the tabs to review Details, Coverage, Eligibility, and Enrollments.
3. Click **Edit** in the page header to open the plan edit form.

## Creating a benefit plan

The New Plan page at `/hr/benefits/plans/new` hosts the benefit plan creation form (`BenefitPlanFormPage` in create mode, HR-11). Gated behind the `hr.benefits.admin` permission. On successful submission the user is returned to the benefit plans list at `/hr/benefits/plans`. Benefit plan records contain compensation-adjacent data.

Before you start: confirm plan details from your benefits carrier or broker; ensure effective dates and plan year are defined.

1. Navigate to `/hr/benefits/plans/new` or choose **New Plan** from the benefit plans list.
2. Complete the plan form fields.
3. Submit; on success you will be returned to the plans list.

**Key concept:** A **Benefit Plan** is a configured benefits offering (e.g., health insurance, dental) that employees can enroll in during open enrollment or qualifying life events.

## Editing a benefit plan

The Edit Plan page at `/hr/benefits/plans/:id/edit` provides a form for updating an existing benefit plan definition (`BenefitPlanFormPage` in edit mode). Requires permission `hr.benefits.admin` (enforced by `RequirePermission` in benefits-routes.tsx).

Before you start: navigate from the benefit plan detail page and click the edit action; consult your benefits administrator before modifying active plans.

1. From a benefit plan detail page, click the edit action. You land on `/hr/benefits/plans/:id/edit`.
2. Update plan name, type, dates, cost-sharing, or other plan details.
3. Submit the form. The plan record is updated.

## Related

<Columns cols={2}>
  <Card title="Human Resources" icon="users" href="/hr/overview">
    Human Resources core overview.
  </Card>

  <Card title="Governance & parity" icon="scale-balanced" href="/governance/index">
    Documentation coverage and governance.
  </Card>
</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/hr.tsx
  * src/routes/hr/benefits-routes.tsx
  * src/cores/hr/benefits/pages/admin/BenefitPlansListPage.tsx
  * src/cores/hr/benefits/pages/admin/BenefitPlanDetailPage.tsx
  * src/cores/hr/benefits/pages/admin/BenefitPlanFormPage.tsx
  * src/cores/hr/benefits/hooks/index.ts
  * src/cores/hr/benefits/hooks/useBenefitPlanDetail.ts
  * src/routes/hr/oversight-analytics-succession-routes.tsx
</Accordion>