@payfit/unity-components

This skill targets the current workspace Unity v3 API. Legacy examples are migration context.

Two entry points expose the same components in two flavors. The base entry (@payfit/unity-components) ships router-agnostic Raw* primitives that take a plain href. The Tanstack integration entry (@payfit/unity-components/integrations/tanstack-router) ships type-safe counterparts that take to and are wired via createLink from @tanstack/react-router.

Setup#

In a Tanstack Router feature plugin, import every link/nav component from the integration entry. No RouterProvider is required — the integration uses Tanstack hooks directly.

import {
  Breadcrumb,
  BreadcrumbLink,
  Breadcrumbs,
  Link,
  Tab,
  TabList,
  TabPanel,
  Tabs,
} from '@payfit/unity-components/integrations/tanstack-router'
import { Outlet } from '@tanstack/react-router'

export function EmployeesShell() {
  return (
    <>
      <Breadcrumbs>
        <Breadcrumb>
          <BreadcrumbLink to="/">Home</BreadcrumbLink>
        </Breadcrumb>
        <Breadcrumb>
          <BreadcrumbLink to="/employees">Employees</BreadcrumbLink>
        </Breadcrumb>
      </Breadcrumbs>

      <Tabs>
        <TabList>
          <Tab to="/employees/active">Active</Tab>
          <Tab to="/employees/archived">Archived</Tab>
        </TabList>
        <TabPanel>
          <Outlet />
        </TabPanel>
      </Tabs>

      <Link to="/employees/new">New employee</Link>
    </>
  )
}

Core Patterns#

• Use router-aware integration exports in TanStack Router features and Raw* primitives for explicit href navigation.
• Preserve the required Breadcrumbs, Pagination, and Tabs composition.
• In non-TanStack applications, provide the appropriate router adapter before using Raw* navigation components.

Read references/patterns.md for complete compositions and provider examples.

Common Mistakes#

HIGH Import Link from base entry in a Tanstack Router feature#

Wrong:

import { Link } from '@payfit/unity-components'
;<Link to="/dashboard">Go</Link>

Correct:

import { Link } from '@payfit/unity-components/integrations/tanstack-router'
;<Link to="/dashboard">Go</Link>

The base export "Link" does not exist; agents alias RawLink and pass to=. The prop is silently ignored and the link does not navigate.

Source: src/modules/tanstack-router/components/link/Link.tsx (createLink wraps RawLink)

HIGH Pass to= prop to RawLink#

Wrong:

import { RawLink } from '@payfit/unity-components'
;<RawLink to="/dashboard">Go</RawLink>

Correct:

// Use the integration Link for type-safe routing:
import { Link } from '@payfit/unity-components/integrations/tanstack-router'
<Link to="/dashboard">Go</Link>
// OR keep RawLink with a plain href:
<RawLink href="/dashboard">Go</RawLink>

RawLink only accepts href. The to prop is silently ignored.

Source: src/core/components/link/RawLink.tsx

HIGH Expect the v1 monolithic Pagination#

Wrong:

import { Pagination, ClientSidePagination } from '@payfit/unity-components'
// ClientSidePagination is not exported; Pagination needs children.
<Pagination currentPage={1} pageCount={10} onPageChange={…} />

Correct:

import { Pagination, PaginationContent, PaginationItem, RawPaginationLink }
  from '@payfit/unity-components'
<Pagination currentPage={1} pageCount={10} onPageChange={…}>
  <PaginationContent>
    <PaginationItem>
      <RawPaginationLink value={1}>1</RawPaginationLink>
    </PaginationItem>
    {/* … */}
  </PaginationContent>
</Pagination>
// Or, for tables, let DataTable handle pagination internally.

v2 Pagination is compositional; passing currentPage/pageCount with no children renders an empty container. The old monolithic component (ClientSidePagination) now lives only inside DataTable as an internal — there is no public monolithic export. For standalone pagination, compose it yourself; for paginated tables, use DataTable which has it built in.

Source: src/core/components/pagination/Pagination.tsx; index.ts

MEDIUM Forget to wrap BreadcrumbLink in Breadcrumb#

Wrong:

<Breadcrumbs>
  <BreadcrumbLink href="/">Home</BreadcrumbLink>
</Breadcrumbs>

Correct:

<Breadcrumbs>
  <Breadcrumb>
    <BreadcrumbLink href="/">Home</BreadcrumbLink>
  </Breadcrumb>
</Breadcrumbs>

Breadcrumbs filters children to Breadcrumb type; loose BreadcrumbLinks are dropped silently.

Source: src/core/components/breadcrumbs/Breadcrumbs.tsx

MEDIUM Use Raw* components without RouterProvider in a non-Tanstack app#

Wrong:

<App>
  <RawLink href="/dashboard">Go</RawLink>
</App>

Correct:

<RouterProvider
  isActive={path => router.isActive(path)}
  navigate={router.navigate}
>
  <App>
    <RawLink href="/dashboard">Go</RawLink>
  </App>
</RouterProvider>

Raw* components consume useRouter() context. Without RouterProvider, isActive checks return undefined and active-link styling is lost.

Source: src/core/components/link/RawLink.tsx; src/core/providers/router/RouterProvider.tsx

See also#

• unity-setup-feature-plugin — where and how to mount RouterProvider, and when a feature plugin should switch from base to integration entry.
• unity-data-table — DataTable has pagination built in; do not compose Pagination next to it.