# How to Configure Astryx Link Component for Next.js, React Router, and Other React Routers
> Configure Astryx Link component for Next.js React Router and more. Seamlessly integrate with any React router using LinkProvider for flexible navigation.
- Repository: [Meta/astryx](https://github.com/facebook/astryx)
- Tags: how-to-guide
- Published: 2026-08-04
---
**Astryx's `Link` component is router-agnostic and renders a native `` by default, but you can replace it with any React router's link component via the `LinkProvider` pattern without changing your API.**
The Astryx design system (facebook/astryx) provides a flexible, context-based solution for integrating its `Link` component with different routing libraries. Whether you're using Next.js, React Router, TanStack Router, or another solution, you can swap the underlying rendering behavior while preserving Astryx's styling, accessibility features, and tooltip support.
## How the Link Provider Pattern Works
Astryx uses three core pieces to enable router flexibility, all located in `packages/core/src/Link/`:
- **[`LinkProvider.tsx`](https://github.com/facebook/astryx/blob/main/LinkProvider.tsx)** – Supplies a custom link component to any subtree via React context
- **[`useLinkComponent.ts`](https://github.com/facebook/astryx/blob/main/useLinkComponent.ts)** – Resolves which component to render and handles prop mapping
- **[`Link.tsx`](https://github.com/facebook/astryx/blob/main/Link.tsx)** – The consumer that applies Astryx's visual and behavioral layer
The resolution hierarchy in [`useLinkComponent.ts`](https://github.com/facebook/astryx/blob/main/useLinkComponent.ts) follows this priority: **per-instance `as` prop > provider component > native ``**. When a custom component replaces the default anchor, Astryx automatically adds a `to` prop (mirroring `href`) so routers expecting `to` work without adapter code.
## Configuring Astryx Link for Next.js
Next.js uses `next/link`, which expects an `href` prop. Since Astryx also uses `href` natively, the integration is straightforward.
Wrap your root layout or app component with `LinkProvider`:
```tsx
// app/layout.tsx (Next.js 13+ App Router)
import {LinkProvider} from '@astryxdesign/core';
import NextLink from 'next/link';
export default function RootLayout({children}: {children: React.ReactNode}) {
return (
{children}
);
}
```
Now all Astryx `Link` components render as `next/link` instances:
```tsx
import {Link} from '@astryxdesign/core';
export function Navigation() {
return (
);
}
```
The `isExternalLink` prop still works correctly—[`useLinkComponent.ts`](https://github.com/facebook/astryx/blob/main/useLinkComponent.ts) detects external URLs and appropriately falls back to standard anchor behavior even when a custom component is provided.
## Configuring Astryx Link for React Router
React Router's `` component expects a `to` prop instead of `href`. Astryx handles this automatically through `createLinkWithTo` in [`useLinkComponent.ts`](https://github.com/facebook/astryx/blob/main/useLinkComponent.ts), which wraps custom components to inject `to={href}`.
Set up your app with `BrowserRouter` and `LinkProvider`:
```tsx
// src/App.tsx
import {BrowserRouter} from 'react-router-dom';
import {LinkProvider} from '@astryxdesign/core';
import {Link as RouterLink} from 'react-router-dom';
export function App() {
return (
{/* Your application routes */}
);
}
```
Write navigation using standard Astryx `href` props:
```tsx
import {Link} from '@astryxdesign/core';
export function AdminSidebar() {
return (
);
}
```
Behind the scenes in [`useLinkComponent.ts`](https://github.com/facebook/astryx/blob/main/useLinkComponent.ts), the wrapper translates your `href` into both `href` and `to` props, satisfying React Router's requirements without code changes.
## Per-Instance Component Override with the `as` Prop
For mixed routing scenarios or one-off exceptions, use the `as` prop to override the component for a single `Link` instance. This bypasses both the provider value and the default anchor.
```tsx
import {Link} from '@astryxdesign/core';
import {Link as RouterLink} from 'react-router-dom';
import NextLink from 'next/link';
export function HybridNavigation() {
return (
<>
{/* Uses provider default (Next.js in this example) */}
Home
{/* Overrides to React Router Link for this instance only */}
Admin Panel
{/* Forces native anchor despite provider */}
Legacy Page
);
}
```
The `as` prop accepts any valid React component type or the string `'a'`, giving you granular control when needed.
## Key Source Files in Astryx
Understanding the implementation details helps debug integration issues:
| File | Purpose |
|------|---------|
| [`LinkProvider.tsx`](https://github.com/facebook/astryx/blob/main/LinkProvider.tsx) | Context provider that stores the custom link component |
| [`useLinkComponent.ts`](https://github.com/facebook/astryx/blob/main/useLinkComponent.ts) | Hook resolving component priority and injecting `to` prop |
| [`Link.tsx`](https://github.com/facebook/astryx/blob/main/Link.tsx) | Core component applying theme, transitions, and accessibility |
| [`LinkContext.ts`](https://github.com/facebook/astryx/blob/main/LinkContext.ts) | React context definition for provider/consumer pair |
| `Link.doc.mjs` | API documentation and prop specifications |
The source code reveals that `useLinkComponent` uses the experimental `use(LinkContext)` API (React 18+) for context reading, and that `createLinkWithTo` is only applied when the resolved component isn't the native `'a'` string.
## Complete TypeScript Example: Multi-Router Setup
Here's a practical pattern for applications transitioning between routers or using micro-frontends with different routing solutions:
```tsx
// components/RouterAwareLink.tsx
import {Link as AstryxLink, LinkProps} from '@astryxdesign/core';
import {Link as RouterLink} from 'react-router-dom';
import NextLink from 'next/link';
type RouterType = 'next' | 'react-router' | 'default';
interface RouterAwareLinkProps extends Omit {
router?: RouterType;
}
const routerComponents: Record> = {
next: NextLink,
'react-router': RouterLink,
default: 'a',
};
export function RouterAwareLink({router = 'default', ...props}: RouterAwareLinkProps) {
return ;
}
```
Usage across your application remains consistent:
```tsx
// In a Next.js page
About
// In a React Router subtree
Profile
// External or static links
External
```
## Summary
- **Astryx `Link` is router-agnostic by design** — start with a native `` and upgrade to framework-specific components via `LinkProvider`
- **`LinkProvider` sets the default** for all descendant links through React context defined in [`LinkContext.ts`](https://github.com/facebook/astryx/blob/main/LinkContext.ts)
- **`useLinkComponent` handles the mapping** — resolves priority chain (`as` > provider > `'a'`) and auto-injects `to` for React Router compatibility
- **No adapter code needed** — the internal `createLinkWithTo` wrapper in [`useLinkComponent.ts`](https://github.com/facebook/astryx/blob/main/useLinkComponent.ts) bridges `href` and `to` prop differences automatically
- **Granular control available** — the `as` prop on individual `Link` instances overrides context for mixed-router scenarios
## Frequently Asked Questions
### Does Astryx Link work with TanStack Router?
Yes. TanStack Router's `Link` component uses a `to` prop like React Router, so the same configuration pattern applies. Wrap your app with `LinkProvider` and pass TanStack's `Link` component—the automatic `to` injection in [`useLinkComponent.ts`](https://github.com/facebook/astryx/blob/main/useLinkComponent.ts) handles the rest.
### Can I use different routers in the same application?
Absolutely. The `as` prop on individual `Link` instances overrides the `LinkProvider` value. You can nest multiple providers at different tree levels, or use per-instance overrides to mix Next.js, React Router, and native links as needed.
### What happens if I don't configure a provider?
Without `LinkProvider`, all Astryx `Link` components render as native `` elements. You retain full styling, accessibility, and tooltip functionality, but lose client-side navigation benefits from your framework's router.
### Does the `isExternalLink` prop work with custom routers?
Yes. The external link detection logic runs before component resolution in [`Link.tsx`](https://github.com/facebook/astryx/blob/main/Link.tsx). External URLs automatically render as native anchors with appropriate `rel` and `target` attributes, regardless of your `LinkProvider` configuration.