# How to Configure XDSLinkProvider for Astryx React Router Integration

> Configure XDSLinkProvider for Astryx React Router integration by wrapping your app with LinkProvider and passing your React Router Link component to enable seamless client-side navigation.

- Repository: [Meta/astryx](https://github.com/facebook/astryx)
- Tags: how-to-guide
- Published: 2026-07-02

---

**Wrap your React application with `LinkProvider` from `@astryxdesign/core` and pass your React Router `Link` component to the `component` prop to enable seamless integration between Astryx's design system and client-side navigation.**

The `facebook/astryx` repository provides XDSLinkProvider as the central mechanism for bridging Astryx components with external routing libraries. By configuring this provider in [`packages/core/src/Link/LinkProvider.tsx`](https://github.com/facebook/astryx/blob/main/packages/core/src/Link/LinkProvider.tsx), you replace native anchor elements with React Router's navigation logic throughout your component tree. This integration ensures that every `Link` component in the design system respects your application's routing configuration.

## Installing the Astryx Core Package

Before configuring the provider, install the Astryx design system core package:

```bash
npm install @astryxdesign/core

```

This package exports `LinkProvider` and the polymorphic `Link` component from the `Link` subdirectory.

## Configuring XDSLinkProvider for React Router

To enable React Router integration, import `LinkProvider` from `@astryxdesign/core/Link` and your router's `Link` component, then wrap your application tree:

```tsx
import { LinkProvider } from '@astryxdesign/core/Link';
import { Link as RouterLink } from 'react-router-dom';

function App() {
  return (
    <LinkProvider component={RouterLink}>
      <BrowserRouter>
        <Routes>
          {/* Your application routes */}
        </Routes>
      </BrowserRouter>
    </LinkProvider>
  );
}

```

The `component` prop accepts any React component that implements the standard link interface (accepting `to`, `href`, `target`, etc.), allowing the provider to register it in the internal `LinkContext` defined in [`packages/core/src/Link/LinkProvider.tsx`](https://github.com/facebook/astryx/blob/main/packages/core/src/Link/LinkProvider.tsx).

## Using the Link Component in Your Application

Once the provider is configured, use the `Link` component from `@astryxdesign/core/Link` throughout your UI. It automatically renders as the React Router component supplied to the provider:

```tsx
import { Link } from '@astryxdesign/core/Link';

function Navigation() {
  return (
    <nav>
      <Link to="/dashboard">Dashboard</Link>
      <Link to="/settings">Settings</Link>
      <Link to="/profile">Profile</Link>
    </nav>
  );
}

```

The `Link` implementation in [`packages/core/src/Link/Link.tsx`](https://github.com/facebook/astryx/blob/main/packages/core/src/Link/Link.tsx) reads the configured component via the `useLinkComponent` hook and forwards all props (`to`, `href`, `target`) to the router-specific implementation.

## Overriding the Provider for Individual Links

For exceptions where a single link must behave differently, use the `as` prop to override the global provider configuration:

```tsx
import { Link } from '@astryxdesign/core/Link';
import { ExternalLink } from './ExternalLink';

function Footer() {
  return (
    <footer>
      <Link as={ExternalLink} href="https://example.com">
        External Site
      </Link>
    </footer>
  );
}

```

This pattern takes precedence over the provider context, allowing specific links to use alternative routing logic or external navigation while maintaining the Astryx design system styling.

## How XDSLinkProvider Works Under the Hood

The provider architecture relies on a React context defined in [`packages/core/src/Link/LinkProvider.tsx`](https://github.com/facebook/astryx/blob/main/packages/core/src/Link/LinkProvider.tsx). This context stores the custom link component and makes it available to any descendant in the tree.

The `Link` component in [`packages/core/src/Link/Link.tsx`](https://github.com/facebook/astryx/blob/main/packages/core/src/Link/Link.tsx) consumes this context through the `useLinkComponent` hook. If no provider exists in the ancestor tree, the component falls back to rendering a standard HTML `<a>` element, ensuring safe incremental adoption.

For reference implementations, examine the custom link template at [`packages/cli/templates/blocks/components/LinkProvider/LinkProviderCustomLink.tsx`](https://github.com/facebook/astryx/blob/main/packages/cli/templates/blocks/components/LinkProvider/LinkProviderCustomLink.tsx) and the Next.js integration example at [`apps/example-nextjs/src/app/providers.tsx`](https://github.com/facebook/astryx/blob/main/apps/example-nextjs/src/app/providers.tsx), which demonstrates similar patterns for framework-specific routers.

## Summary

- **Install `@astryxdesign/core`** to access the `LinkProvider` and `Link` components.
- **Wrap your application** with `LinkProvider` and pass your router's `Link` component to the `component` prop.
- **Use `Link` from `@astryxdesign/core/Link`** throughout your app for automatic React Router integration.
- **Override individual links** with the `as` prop when specific routing behavior is required.
- **Fallback behavior**: Without a provider, `Link` renders as a standard `<a>` tag, ensuring backward compatibility.

## Frequently Asked Questions

### What is XDSLinkProvider in the Astryx design system?

XDSLinkProvider is the context provider exported as `LinkProvider` from `@astryxdesign/core/Link` that injects custom routing components into Astryx's polymorphic `Link` elements. It enables seamless integration with React Router, Next.js, or any other client-side navigation library by establishing a global link component configuration.

### Can I use XDSLinkProvider with Next.js App Router instead of React Router?

Yes, you can configure XDSLinkProvider for Next.js by importing the Next.js `Link` component and passing it to the `component` prop. The provider is framework-agnostic and accepts any component that handles navigation props, as demonstrated in the example file [`apps/example-nextjs/src/app/providers.tsx`](https://github.com/facebook/astryx/blob/main/apps/example-nextjs/src/app/providers.tsx).

### Why is my Link component still rendering as a plain anchor tag?

If `Link` renders as a standard `<a>` element, verify that you have imported `Link` from `@astryxdesign/core/Link` (not a different package) and that a `LinkProvider` ancestor exists in your component tree. Without the provider context, the component intentionally defaults to native anchor tag behavior for progressive enhancement.

### How do I access the configured link component programmatically in child components?

Use the `useLinkComponent` hook exported from `@astryxdesign/core/Link` to retrieve the currently configured link component within any descendant of the provider. This hook returns the component type stored in `LinkContext`, allowing you to programmatically render router-aware links or build higher-order components that respect the provider configuration.