How to Configure XDSLinkProvider for Astryx React Router Integration

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, 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:

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:

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.

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:

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 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:

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. 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 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 and the Next.js integration example at 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.

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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}