Skip to main content
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:
DestinationRequired ParamsDescription
employee_list—Employee directory
employee_profileemployeeIdA specific employee’s profile
contractor_list—Contractor directory
contractor_profilecontractorIdA specific contractor’s profile
payroll_list—Payroll runs list for the current business entity
payrollpayrollIdA 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). 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. 
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' },
  },
});
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. 
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 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.). 
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: 
<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.