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

# Deep Linking

> Navigate users directly to specific pages within the Nmbr Component.

Deep linking allows you to programmatically navigate users to specific pages within the Nmbr Component — for example, opening directly to an employee profile or a specific payroll run. This lets you build your own navigation experiences around the component without needing to know its internal route structure.

## How It Works

Instead of exposing internal route paths (which can change), the component provides a set of **named destinations** — stable, semantic identifiers like `employee_profile` or `payroll_list`. You reference these destinations by name, and the component handles routing internally.

Deep linking controls where the user **starts** or **navigates to**. It does not hide any pages or restrict navigation — all tabs and pages remain accessible. Think of it as "start here", not "only show this".

## Destinations

The following destinations are available:

| Destination             | Required Params | Description                                       |
| ----------------------- | --------------- | ------------------------------------------------- |
| `employee_list`         | —               | Employee directory                                |
| `employee_profile`      | `employeeId`    | A specific employee's profile                     |
| `contractor_list`       | —               | Contractor directory                              |
| `contractor_profile`    | `contractorId`  | A specific contractor's profile                   |
| `payroll_list`          | —               | Payroll runs list for the current business entity |
| `payroll`               | `payrollId`     | A specific payroll run                            |
| `business_settings`     | —               | Business entity settings                          |
| `year_end_tax_packages` | —               | Year-end tax packages                             |
| `reports`               | —               | Reports page                                      |
| `roes`                  | —               | Records of Employment                             |

Destinations that require a `businessEntityId` internally (like `payroll_list`, `business_settings`, etc.) resolve it automatically from the user's current context — you do not need to provide it.

## Usage

There are two ways to deep link: at **load time** (when the component first mounts) and **after load** (navigate an already-loaded component).

### Navigate on Load

Pass a `destination` in the options when calling `load()`. The component will navigate to that page as soon as it is ready, avoiding a flash of the default landing page.

```javascript theme={null}
const host = ComponentsHost.initialize({
  companyId: 'your-company-id',
  partnerId: 'your-partner-id',
  signingUrl: '/sign_nmbr_request',
});

// Navigate to the employee list on load
const portal = host.load(container, {
  destination: { name: 'employee_list' },
});

// Navigate to a specific employee profile on load
const portal = host.load(container, {
  destination: {
    name: 'employee_profile',
    params: { employeeId: 'emp_01ABC123' },
  },
});
```

### Navigate After Load

Use the `goto()` method on a loaded portal frame to navigate at any time. This is useful when your app has its own navigation (e.g., sidebar links, buttons) that should control what the component displays.

```javascript theme={null}
const portal = host.load(container);

// Later, in response to user action in your app:
await portal.goto('employee_profile', { employeeId: 'emp_01ABC123' });

// Navigate to a page without params:
await portal.goto('payroll_list');
```

`goto()` returns a promise that resolves once the navigation message has been sent to the component. You can safely call `goto()` before or after the component is ready — it will wait for the connection to be established.

## Works with Customization Settings

Deep linking does not hide anything on its own — but the component continues to obey all [customization settings](/components/customization) you have configured. This means you can combine deep linking with settings like `hideNavigationMenu`, tab visibility, and other options to fully tailor the experience.

For example, if you set `hideNavigationMenu: true`, the component's built-in navigation menu is hidden. You can then use `goto()` to build your own navigation that controls which page the component displays. The component will still respect any other customization settings you have in place (hidden tabs, disabled buttons, etc.).

```javascript theme={null}
const host = ComponentsHost.initialize({
  companyId: 'your-company-id',
  partnerId: 'your-partner-id',
  signingUrl: '/sign_nmbr_request',
  settings: {
    hideNavigationMenu: true, // hide the built-in navigation menu
    employeeTabs: {
      hideBenefits: true,     // still respected alongside deep linking
    },
  },
});

const portal = host.load(container, {
  destination: { name: 'employee_list' },
});

// Your app now fully controls navigation via goto()
```

## Example: Building a Custom Navigation

A common pattern is to build your own sidebar or tab navigation that controls which page the component displays:

```html theme={null}
<nav id="payroll-nav">
  <button data-destination="employee_list">Employees</button>
  <button data-destination="contractor_list">Contractors</button>
  <button data-destination="payroll_list">Payroll</button>
  <button data-destination="reports">Reports</button>
</nav>
<div id="nmbr-container"></div>

<script>
  const host = ComponentsHost.initialize({
    companyId: 'your-company-id',
    partnerId: 'your-partner-id',
    signingUrl: '/sign_nmbr_request',
  });

  const portal = host.load(document.getElementById('nmbr-container'));

  document.getElementById('payroll-nav').addEventListener('click', (e) => {
    const destination = e.target.dataset.destination;
    if (destination) {
      portal.goto(destination);
    }
  });
</script>
```

## Important Notes

* **Deep linking does not hide anything.** Users can still navigate freely within the component after landing on the destination. It only controls the starting point.
* **Destination names are a stable API.** Unlike internal route paths, destination names will not change without a deprecation notice. You can safely hard-code them.
* **Business entity context is automatic.** For destinations that are scoped to a business entity (like `payroll_list` or `business_settings`), the component resolves the business entity from the user's current context. You do not need to pass a `businessEntityId`.
* **Invalid destinations are handled gracefully.** If an unrecognized destination name is passed, the component falls back to the default landing page.