From ab781e162333e28c0951f5867a45d2c5c6d59b75 Mon Sep 17 00:00:00 2001
From: Virginia Czosek <virginia.czosek@cfpb.gov>
Date: Thu, 30 Apr 2026 15:26:07 -0700
Subject: [PATCH 1/9] Add ability to configure DSR to use router link
 component.

---
 src/components/Breadcrumb/breadcrumb.tsx      |  9 +--
 src/components/Header/responsive-menu.tsx     | 10 +--
 src/components/Link/base-link.tsx             | 20 ++++++
 src/components/Link/link.tsx                  | 72 +++++--------------
 src/components/SecondaryNav/secondary-nav.tsx | 14 ++--
 src/context/dsr-context.tsx                   | 31 ++++++++
 src/index.ts                                  | 12 ++++
 7 files changed, 98 insertions(+), 70 deletions(-)
 create mode 100644 src/components/Link/base-link.tsx
 create mode 100644 src/context/dsr-context.tsx

diff --git a/src/components/Breadcrumb/breadcrumb.tsx b/src/components/Breadcrumb/breadcrumb.tsx
index 82797ad4b1..5ddbe2011a 100644
--- a/src/components/Breadcrumb/breadcrumb.tsx
+++ b/src/components/Breadcrumb/breadcrumb.tsx
@@ -3,9 +3,10 @@ import type { HTMLAttributes } from 'react';
 import { Fragment } from 'react';
 import './breadcrumb.scss';
 import { JSXElement } from '../../types/jsx-element';
+import Link from '~/src/components/Link/link';
 
 export interface BreadcrumbCrumb {
-  href: string;
+  to: string;
   label: string;
   isCurrent?: boolean;
 }
@@ -34,16 +35,16 @@ export const Breadcrumb = ({
     >
       <nav className='m-breadcrumbs' aria-label={ariaLabel}>
         {crumbs.map((crumb) => (
-          <Fragment key={`${crumb.href}-${crumb.label}`}>
+          <Fragment key={`${crumb.to}-${crumb.label}`}>
             {` / `}
             {crumb.isCurrent ? (
               <span className='m-breadcrumbs__crumb' aria-current='page'>
                 {` ${crumb.label} `}
               </span>
             ) : (
-              <a className='m-breadcrumbs__crumb' href={crumb.href}>
+              <Link className='m-breadcrumbs__crumb' to={crumb.to}>
                 {` ${crumb.label} `}
-              </a>
+              </Link>
             )}
           </Fragment>
         ))}
diff --git a/src/components/Header/responsive-menu.tsx b/src/components/Header/responsive-menu.tsx
index fb47d12ac8..e6adb5fb9b 100644
--- a/src/components/Header/responsive-menu.tsx
+++ b/src/components/Header/responsive-menu.tsx
@@ -17,7 +17,7 @@ export function CfpbLogo({
   return (
     <Link
       data-testid='CfpbLogoLink'
-      href={href}
+      to={href}
       title='Home'
       aria-label='Home'
       className='o-header__logo'
@@ -140,18 +140,18 @@ export default function ResponsiveMenu({
   );
 }
 
-export const ExampleLinks: ReactNode[] = [
-  <Link key='home' href='/' label='Home' />,
+export const ExampleLinks: React.ReactNode[] = [
+  <Link key='home' to='/' label='Home' />,
   <Link
     key='filing'
     className='nav-item active'
-    href='/filing'
+    to='/filing'
     label='Filing'
   />,
   <Link
     key='profile'
     className='nav-item profile'
-    href='/profile'
+    to='/profile'
     label='John Sample'
   />,
   <Button
diff --git a/src/components/Link/base-link.tsx b/src/components/Link/base-link.tsx
new file mode 100644
index 0000000000..60685bad0c
--- /dev/null
+++ b/src/components/Link/base-link.tsx
@@ -0,0 +1,20 @@
+import { ReactNode } from "react";
+import type { JSXElement } from "~/src/types/jsx-element";
+
+export interface BaseLinkProperties {
+  to: string | undefined;
+  children: ReactNode;
+  [key: string]: unknown;
+}
+
+export const BaseLink = ({
+  to,
+  children,
+  ...others
+}: BaseLinkProperties): JSXElement | null => {
+  return (
+    <a href={to} {...others}>
+      {children}
+    </a>
+  );
+};
\ No newline at end of file
diff --git a/src/components/Link/link.tsx b/src/components/Link/link.tsx
index fa86b4f17f..cca258cbfd 100644
--- a/src/components/Link/link.tsx
+++ b/src/components/Link/link.tsx
@@ -1,9 +1,8 @@
 import { JSX } from 'react';
-import { Link as RouterLink } from 'react-router';
 import type { JSXElement } from '../../types/jsx-element';
-
 import classnames from 'classnames';
 import type { HTMLProps, ReactNode, Ref } from 'react';
+import { useDSRContext } from '~/src/context/dsr-context';
 import { Icon } from '../Icon/icon';
 import ListItem from '../List/list-item';
 import './link.scss';
@@ -20,23 +19,19 @@ export interface LinkProperties extends HTMLProps<HTMLAnchorElement> {
   /**
    * The link's destination URL.
    */
-  href: string;
+  to: string | undefined;
   /**
-   * Name of icon to display left of link text
+   * Name of icon to display adjacent to link text
    */
-  iconLeft?: string;
+  iconName?: string;
   /**
-   * Name of icon to display right of link text
+   * Whether to display the icon to the left or right of text
    */
-  iconRight?: string;
+  iconPosition?: 'left' | 'right'; 
   /**
    * Whether the link is a standalone link
    */
   isJump?: boolean;
-  /**
-   * Whether the link is a react router link
-   */
-  isRouterLink?: boolean;
   /**
    * The link's text content, not required if children are provided
    */
@@ -57,19 +52,16 @@ export interface LinkProperties extends HTMLProps<HTMLAnchorElement> {
 export default function Link({
   isButton = false,
   children,
-  href,
-  iconLeft,
-  iconRight,
+  to,
+  iconName,
+  iconPosition = 'left',
   isJump = false,
-  isRouterLink = false,
   label,
   type = 'default',
   ...others
 }: LinkProperties): JSXElement {
-  const hasLeftIcon = Boolean(iconLeft);
-  const hasRightIcon = Boolean(iconRight);
-  const hasIcons = hasLeftIcon || hasRightIcon;
-  const shouldUseLinkStyles = !isButton && (hasIcons || isJump);
+  const hasIcon = Boolean(iconName);
+  const shouldUseLinkStyles = !isButton && (hasIcon || isJump);
   const shouldWrapLabel = isButton || shouldUseLinkStyles;
   const labelNode = shouldWrapLabel ? <LinkText>{label}</LinkText> : label;
   const cname = classnames(others.className, {
@@ -80,47 +72,19 @@ export default function Link({
     'a-link': shouldUseLinkStyles,
   });
 
-  if (hasLeftIcon && hasRightIcon) {
-    throw new Error(
-      'Link component: only one of iconLeft or iconRight can be provided',
-    );
-  }
-
-  if (isRouterLink) {
-    if (!href) {
-      throw new Error(
-        'Link component: href is a required attribute when isRouterLink is true',
-      );
-    }
-    return (
-      <RouterLink to={href} {...others} className={cname}>
-        {children}
-        {!!iconLeft && (
-          <Icon name={iconLeft} isPresentational data-testid='link-icon-left' />
-        )}
-        {labelNode}
-        {!!iconRight && (
-          <Icon
-            name={iconRight}
-            isPresentational
-            data-testid='link-icon-right'
-          />
-        )}
-      </RouterLink>
-    );
-  }
+  const { LinkComponent } = useDSRContext();
 
   return (
-    <a {...others} className={cname} href={href}>
+    <LinkComponent {...others} className={cname} to={to}>
       {children}
-      {!!iconLeft && (
-        <Icon name={iconLeft} isPresentational data-testid='link-icon-left' />
+      {iconName && iconPosition !== 'right' && (
+        <Icon name={iconName} isPresentational data-testid='link-icon-left' />
       )}
       {labelNode}
-      {!!iconRight && (
-        <Icon name={iconRight} isPresentational data-testid='link-icon-right' />
+      {iconName && iconPosition == 'right' && (
+        <Icon name={iconName} isPresentational data-testid='link-icon-right' />
       )}
-    </a>
+    </LinkComponent>
   );
 }
 
diff --git a/src/components/SecondaryNav/secondary-nav.tsx b/src/components/SecondaryNav/secondary-nav.tsx
index ba9e1903f2..64d1a12f20 100644
--- a/src/components/SecondaryNav/secondary-nav.tsx
+++ b/src/components/SecondaryNav/secondary-nav.tsx
@@ -5,13 +5,13 @@ import Link from '../Link/link';
 import './secondary-nav.scss';
 
 export interface SecondaryNavChildItem {
-  href: string;
+  to: string;
   label: string;
   isActive?: boolean;
 }
 
 export interface SecondaryNavItem {
-  href?: string;
+  to?: string;
   label: string;
   /**
    * Whether this item is the current page. Ignored when the item has children;
@@ -61,13 +61,13 @@ export const SecondaryNav = ({
 
             return (
               <li
-                key={item.href ?? item.label}
+                key={item.to ?? item.label}
                 className='o-secondary-nav__item'
                 data-nav-is-active={sectionHasActive ? 'true' : undefined}
               >
-                {item.href ? (
+                {item.to ? (
                   <Link
-                    href={item.href}
+                    to={item.to}
                     className={classnames(
                       'o-secondary-nav__link o-secondary-nav__link--parent',
                       parentIsActive && 'o-secondary-nav__link--current',
@@ -88,9 +88,9 @@ export const SecondaryNav = ({
                 {item.children && item.children.length > 0 ? (
                   <ul className='o-secondary-nav__list o-secondary-nav__list--children'>
                     {item.children.map((child) => (
-                      <li key={child.href} className='o-secondary-nav__item'>
+                      <li key={child.to} className='o-secondary-nav__item'>
                         <Link
-                          href={child.href}
+                          to={child.to}
                           className={classnames(
                             'o-secondary-nav__link',
                             child.isActive && 'o-secondary-nav__link--current',
diff --git a/src/context/dsr-context.tsx b/src/context/dsr-context.tsx
new file mode 100644
index 0000000000..1e0f5f4140
--- /dev/null
+++ b/src/context/dsr-context.tsx
@@ -0,0 +1,31 @@
+import { createContext, use } from 'react'
+import type { ReactNode } from 'react';
+import { BaseLink } from '~/src/components/Link/base-link';
+import type { BaseLinkProperties } from '~/src/components/Link/base-link';
+
+
+export interface DSRContextType {
+  LinkComponent: React.ComponentType<BaseLinkProperties>;
+}
+
+export const DSRContext = createContext<DSRContextType>({
+  LinkComponent: BaseLink,
+});
+
+export const useDSRContext = () => use(DSRContext);
+
+export interface DSRProviderProperties {
+  LinkComponent: React.ComponentType<BaseLinkProperties> | null;
+  children?: ReactNode;
+};
+
+export const DSRProvider = ({ children, LinkComponent }: { 
+  children: ReactNode; 
+  LinkComponent: React.ComponentType<BaseLinkProperties>;
+}) => {
+  return (
+    <DSRContext value={{LinkComponent: LinkComponent}}>
+      {children}
+    </DSRContext>
+  );
+};
diff --git a/src/index.ts b/src/index.ts
index 3a0810699f..60e9bda147 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -6,6 +6,7 @@ export { AlertFieldLevel } from './components/Alert/alert-field-level';
 export { Banner } from './components/Banner/banner';
 export { LanguageLink } from './components/Banner/banner-language-link';
 export { Breadcrumb } from './components/Breadcrumb/breadcrumb';
+export type { BreadcrumbCrumb } from './components/Breadcrumb/breadcrumb';
 export { Button } from './components/Buttons/button';
 export { ButtonGroup } from './components/Buttons/button-group';
 export { Checkbox } from './components/Checkbox/checkbox';
@@ -22,6 +23,8 @@ export { default as Hero } from './components/Hero/hero';
 export { Icon } from './components/Icon/icon';
 export { Label } from './components/Label/label';
 export { default as Layout } from './components/Layout/layout';
+export { BaseLink } from './components/Link/base-link';
+export type { BaseLinkProperties } from './components/Link/base-link';
 export { default as Link, LinkText, ListLink } from './components/Link/link';
 export type { LinkProperties } from './components/Link/link';
 export { default as List } from './components/List/list';
@@ -55,3 +58,12 @@ export {
   TextIntroductionSubheading,
 } from './components/TextIntroduction/text-introduction';
 export { WellContainer, WellContent } from './components/Well/well';
+export { 
+  useDSRContext,
+  DSRProvider,
+  DSRContext, 
+} from './context/dsr-context';
+export type { 
+  DSRContextType, 
+  DSRProviderProperties} 
+from './context/dsr-context';

From 6d154d890bbc3f45ecc2cdd42b9ab83d811d3040 Mon Sep 17 00:00:00 2001
From: Virginia Czosek <virginia.czosek@cfpb.gov>
Date: Mon, 4 May 2026 13:35:36 -0700
Subject: [PATCH 2/9] Link test updates

---
 src/components/Link/link.test.tsx | 72 ++++++++++++-------------------
 1 file changed, 28 insertions(+), 44 deletions(-)

diff --git a/src/components/Link/link.test.tsx b/src/components/Link/link.test.tsx
index dacb77da9e..fc6ab9d8bf 100644
--- a/src/components/Link/link.test.tsx
+++ b/src/components/Link/link.test.tsx
@@ -1,11 +1,13 @@
 import '@testing-library/jest-dom';
 import { render, screen } from '@testing-library/react';
-import { MemoryRouter } from 'react-router';
 import Link, { LinkText, ListLink } from './link';
+import { DSRContext } from '~/src/context/dsr-context';
+import { ReactNode } from 'react';
+import type { JSXElement } from "~/src/types/jsx-element";
 
 describe('<Link />', () => {
   const linkBaseProperties = {
-    href: '/foo/bar',
+    to: '/foo/bar',
     'data-testid': 'link-test-id',
     label: 'some link',
   };
@@ -31,7 +33,7 @@ describe('<Link />', () => {
   });
 
   it('Option: leftIcon - it adds left icon', async () => {
-    render(<Link {...linkBaseProperties} iconLeft='left' />);
+    render(<Link {...linkBaseProperties} iconName='left' />);
     const link = screen.getByTestId(testId);
     expect(link).toHaveClass('a-link');
     expect(screen.getByText('some link')).toHaveClass('a-link__text');
@@ -39,23 +41,13 @@ describe('<Link />', () => {
   });
 
   it('Option: rightIcon - it adds right icon', async () => {
-    render(<Link {...linkBaseProperties} iconRight='right' />);
+    render(<Link {...linkBaseProperties} iconName='right' iconPosition='right' />);
     const link = screen.getByTestId(testId);
     expect(link).toHaveClass('a-link');
     expect(screen.getByText('some link')).toHaveClass('a-link__text');
     expect(await screen.findByTestId('link-icon-right')).toBeInTheDocument();
   });
 
-  it('Throws an error when both left and right icons are provided', () => {
-    expect(() =>
-      render(
-        <Link {...linkBaseProperties} iconLeft='left' iconRight='right' />,
-      ),
-    ).toThrow(
-      'Link component: only one of iconLeft or iconRight can be provided',
-    );
-  });
-
   it('Option: isButton - it does not add a-link and wraps the label', () => {
     render(<Link {...linkBaseProperties} isButton />);
     const link = screen.getByTestId(testId);
@@ -65,7 +57,7 @@ describe('<Link />', () => {
   });
 
   it('Option: isButton with icon - it keeps a-btn, skips a-link, and shows icon', async () => {
-    render(<Link {...linkBaseProperties} isButton iconRight='right' />);
+    render(<Link {...linkBaseProperties} isButton iconPosition='right' iconName='right' />);
     const link = screen.getByTestId(testId);
     expect(link).toHaveClass('a-btn');
     expect(link).not.toHaveClass('a-link');
@@ -79,42 +71,34 @@ describe('<Link />', () => {
     expect(link).toHaveAttribute('target', '_blank');
   });
 
-  it('Option: isRouterLink - it renders a router link', () => {
-    render(
-      <MemoryRouter initialEntries={['/foo/bar']}>
-        <Link {...linkBaseProperties} isRouterLink />
-      </MemoryRouter>,
-    );
 
-    const link = screen.getByRole('link', { name: /some link/i });
-    expect(link).toHaveAttribute('href', '/foo/bar');
-  });
 
-  it('Option: isRouterLink - it renders children and icons', async () => {
+  it('Context: uses link component configured in context', () => {
+    interface TestLinkProperties {
+      to: string | undefined;
+      children: ReactNode;
+    }
+    const TestLink = ({
+      to,
+      children,
+      ...others
+    }: TestLinkProperties): JSXElement | null => {
+      return (
+        <a href={to} {...others} data-testid='link-component-from-context'>
+          {children}
+        </a>
+      );
+    };
     render(
-      <MemoryRouter initialEntries={['/foo/bar']}>
-        <Link {...linkBaseProperties} isRouterLink iconLeft='left'>
+      <DSRContext value={{LinkComponent:TestLink}}>
+        <Link {...linkBaseProperties}>
           <span data-testid='link-child'>Child</span>
         </Link>
-      </MemoryRouter>,
+      </DSRContext>,
     );
 
-    const link = screen.getByRole('link', { name: /some link/i });
-    expect(link).toHaveClass('a-link');
-    expect(screen.getByTestId('link-child')).toBeInTheDocument();
-    expect(screen.getByText('some link')).toHaveClass('a-link__text');
-    expect(await screen.findByTestId('link-icon-left')).toBeInTheDocument();
-  });
+    expect(screen.getByTestId('link-component-from-context')).toBeInTheDocument();
 
-  it('Option: isRouterLink - it requires href', () => {
-    const brokenProperties = {
-      ...linkBaseProperties,
-      href: undefined as unknown as string,
-    };
-
-    expect(() => render(<Link {...brokenProperties} isRouterLink />)).toThrow(
-      'Link component: href is a required attribute when isRouterLink is true',
-    );
   });
 });
 
@@ -131,7 +115,7 @@ describe('<ListLink>', () => {
   const testId = 'list-link';
 
   it('includes all expected elements', () => {
-    render(<ListLink data-testid={testId} href='/foo/bar' label='Test text' />);
+    render(<ListLink data-testid={testId} to='/foo/bar' label='Test text' />);
     // ListItem
     const listItem = screen.getByRole('listitem');
     expect(listItem).toBeInTheDocument();

From 553a1f618656a43e0588705cab26778cc865ca3f Mon Sep 17 00:00:00 2001
From: Virginia Czosek <virginia.czosek@cfpb.gov>
Date: Mon, 4 May 2026 13:55:01 -0700
Subject: [PATCH 3/9] Revert link icon changes.

---
 src/components/Breadcrumb/breadcrumb.test.tsx | 10 ++--
 src/components/Link/link.test.tsx             | 53 +++++++++++--------
 src/components/Link/link.tsx                  | 33 +++++++-----
 .../SecondaryNav/secondary-nav.test.tsx       | 10 ++--
 4 files changed, 63 insertions(+), 43 deletions(-)

diff --git a/src/components/Breadcrumb/breadcrumb.test.tsx b/src/components/Breadcrumb/breadcrumb.test.tsx
index 9a50ec95b4..ac05b34d2a 100644
--- a/src/components/Breadcrumb/breadcrumb.test.tsx
+++ b/src/components/Breadcrumb/breadcrumb.test.tsx
@@ -13,7 +13,7 @@ describe('<Breadcrumb />', () => {
       <Breadcrumb
         crumbs={[
           {
-            href: '/home',
+            to: '/home',
             label: 'Home',
           },
         ]}
@@ -32,8 +32,8 @@ describe('<Breadcrumb />', () => {
     render(
       <Breadcrumb
         crumbs={[
-          { href: '/home', label: 'Home' },
-          { href: '/section', label: 'Section' },
+          { to: '/home', label: 'Home' },
+          { to: '/section', label: 'Section' },
         ]}
       />,
     );
@@ -49,8 +49,8 @@ describe('<Breadcrumb />', () => {
     render(
       <Breadcrumb
         crumbs={[
-          { href: '/home', label: 'Home' },
-          { href: '/current', label: 'Current', isCurrent: true },
+          { to: '/home', label: 'Home' },
+          { to: '/current', label: 'Current', isCurrent: true },
         ]}
       />,
     );
diff --git a/src/components/Link/link.test.tsx b/src/components/Link/link.test.tsx
index fc6ab9d8bf..fd67d33d40 100644
--- a/src/components/Link/link.test.tsx
+++ b/src/components/Link/link.test.tsx
@@ -13,6 +13,23 @@ describe('<Link />', () => {
   };
   const testId = linkBaseProperties['data-testid'];
 
+  interface CustomLinkProperties {
+      to: string | undefined;
+      children: ReactNode;
+  }
+
+  const CustomLinkComponent = ({
+    to,
+    children,
+    ...others
+  }: CustomLinkProperties): JSXElement | null => {
+    return (
+      <a href={to} {...others} data-testid='link-component-from-context'>
+        {children}
+      </a>
+    );
+  };
+
   it('Type: "default"', () => {
     render(<Link {...linkBaseProperties} />);
     const link = screen.getByTestId(testId);
@@ -33,7 +50,7 @@ describe('<Link />', () => {
   });
 
   it('Option: leftIcon - it adds left icon', async () => {
-    render(<Link {...linkBaseProperties} iconName='left' />);
+    render(<Link {...linkBaseProperties} iconLeft='left' />);
     const link = screen.getByTestId(testId);
     expect(link).toHaveClass('a-link');
     expect(screen.getByText('some link')).toHaveClass('a-link__text');
@@ -41,7 +58,7 @@ describe('<Link />', () => {
   });
 
   it('Option: rightIcon - it adds right icon', async () => {
-    render(<Link {...linkBaseProperties} iconName='right' iconPosition='right' />);
+    render(<Link {...linkBaseProperties} iconRight='right' />);
     const link = screen.getByTestId(testId);
     expect(link).toHaveClass('a-link');
     expect(screen.getByText('some link')).toHaveClass('a-link__text');
@@ -57,7 +74,7 @@ describe('<Link />', () => {
   });
 
   it('Option: isButton with icon - it keeps a-btn, skips a-link, and shows icon', async () => {
-    render(<Link {...linkBaseProperties} isButton iconPosition='right' iconName='right' />);
+    render(<Link {...linkBaseProperties} isButton iconRight='right' />);
     const link = screen.getByTestId(testId);
     expect(link).toHaveClass('a-btn');
     expect(link).not.toHaveClass('a-link');
@@ -71,26 +88,9 @@ describe('<Link />', () => {
     expect(link).toHaveAttribute('target', '_blank');
   });
 
-
-
   it('Context: uses link component configured in context', () => {
-    interface TestLinkProperties {
-      to: string | undefined;
-      children: ReactNode;
-    }
-    const TestLink = ({
-      to,
-      children,
-      ...others
-    }: TestLinkProperties): JSXElement | null => {
-      return (
-        <a href={to} {...others} data-testid='link-component-from-context'>
-          {children}
-        </a>
-      );
-    };
     render(
-      <DSRContext value={{LinkComponent:TestLink}}>
+      <DSRContext value={{LinkComponent:CustomLinkComponent}}>
         <Link {...linkBaseProperties}>
           <span data-testid='link-child'>Child</span>
         </Link>
@@ -100,6 +100,17 @@ describe('<Link />', () => {
     expect(screen.getByTestId('link-component-from-context')).toBeInTheDocument();
 
   });
+
+  it('Context: uses base link component by default', () => {
+    render(
+        <Link {...linkBaseProperties}>
+          <span data-testid='link-child'>Child</span>
+        </Link>,
+    );
+
+    expect(screen.queryByTestId('link-component-from-context')).not.toBeInTheDocument();
+
+  });
 });
 
 describe('<LinkText>', () => {
diff --git a/src/components/Link/link.tsx b/src/components/Link/link.tsx
index cca258cbfd..07f4d0268c 100644
--- a/src/components/Link/link.tsx
+++ b/src/components/Link/link.tsx
@@ -21,13 +21,13 @@ export interface LinkProperties extends HTMLProps<HTMLAnchorElement> {
    */
   to: string | undefined;
   /**
-   * Name of icon to display adjacent to link text
+   * Name of icon to display left of link text
    */
-  iconName?: string;
+  iconLeft?: string;
   /**
-   * Whether to display the icon to the left or right of text
+   * Name of icon to display right of link text
    */
-  iconPosition?: 'left' | 'right'; 
+  iconRight?: string;
   /**
    * Whether the link is a standalone link
    */
@@ -53,15 +53,17 @@ export default function Link({
   isButton = false,
   children,
   to,
-  iconName,
-  iconPosition = 'left',
+  iconLeft,
+  iconRight,
   isJump = false,
   label,
   type = 'default',
   ...others
 }: LinkProperties): JSXElement {
-  const hasIcon = Boolean(iconName);
-  const shouldUseLinkStyles = !isButton && (hasIcon || isJump);
+  const hasLeftIcon = Boolean(iconLeft);
+  const hasRightIcon = Boolean(iconRight);
+  const hasIcons = hasLeftIcon || hasRightIcon;
+  const shouldUseLinkStyles = !isButton && (hasIcons || isJump);
   const shouldWrapLabel = isButton || shouldUseLinkStyles;
   const labelNode = shouldWrapLabel ? <LinkText>{label}</LinkText> : label;
   const cname = classnames(others.className, {
@@ -74,15 +76,22 @@ export default function Link({
 
   const { LinkComponent } = useDSRContext();
 
+  if (hasLeftIcon && hasRightIcon) {
+    throw new Error(
+      'Link component: only one of iconLeft or iconRight can be provided',
+    );
+  }
+
   return (
     <LinkComponent {...others} className={cname} to={to}>
       {children}
-      {iconName && iconPosition !== 'right' && (
-        <Icon name={iconName} isPresentational data-testid='link-icon-left' />
+ 
+      {!!iconLeft && (
+        <Icon name={iconLeft} isPresentational data-testid='link-icon-left' />
       )}
       {labelNode}
-      {iconName && iconPosition == 'right' && (
-        <Icon name={iconName} isPresentational data-testid='link-icon-right' />
+      {!!iconRight && (
+        <Icon name={iconRight} isPresentational data-testid='link-icon-right' />
       )}
     </LinkComponent>
   );
diff --git a/src/components/SecondaryNav/secondary-nav.test.tsx b/src/components/SecondaryNav/secondary-nav.test.tsx
index 3d3b1b5704..31eb1bcfef 100644
--- a/src/components/SecondaryNav/secondary-nav.test.tsx
+++ b/src/components/SecondaryNav/secondary-nav.test.tsx
@@ -5,9 +5,9 @@ import type { SecondaryNavItem } from './secondary-nav';
 
 describe('<SecondaryNav />', () => {
   const defaultItems: SecondaryNavItem[] = [
-    { href: '/a', label: 'Link A' },
-    { href: '/b', label: 'Link B', isActive: true },
-    { href: '/c', label: 'Link C' },
+    { to: '/a', label: 'Link A' },
+    { to: '/b', label: 'Link B', isActive: true },
+    { to: '/c', label: 'Link C' },
   ];
 
   it('renders a nav with the default aria-label', () => {
@@ -62,8 +62,8 @@ describe('<SecondaryNav />', () => {
         label: 'Parent',
         isActive: true,
         children: [
-          { href: '/child-a', label: 'Child A', isActive: true },
-          { href: '/child-b', label: 'Child B' },
+          { to: '/child-a', label: 'Child A', isActive: true },
+          { to: '/child-b', label: 'Child B' },
         ],
       },
     ];

From 69dd2ed2a9e2364a31213c737459fb8582b87f9f Mon Sep 17 00:00:00 2001
From: Virginia Czosek <virginia.czosek@cfpb.gov>
Date: Mon, 4 May 2026 14:00:19 -0700
Subject: [PATCH 4/9] Restore icon test

---
 src/components/Link/link.test.tsx | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/src/components/Link/link.test.tsx b/src/components/Link/link.test.tsx
index fd67d33d40..ca51e87678 100644
--- a/src/components/Link/link.test.tsx
+++ b/src/components/Link/link.test.tsx
@@ -65,6 +65,16 @@ describe('<Link />', () => {
     expect(await screen.findByTestId('link-icon-right')).toBeInTheDocument();
   });
 
+  it('Throws an error when both left and right icons are provided', () => {
+    expect(() =>
+      render(
+        <Link {...linkBaseProperties} iconLeft='left' iconRight='right' />,
+      ),
+    ).toThrow(
+      'Link component: only one of iconLeft or iconRight can be provided',
+    );
+  });
+
   it('Option: isButton - it does not add a-link and wraps the label', () => {
     render(<Link {...linkBaseProperties} isButton />);
     const link = screen.getByTestId(testId);

From 1e8ba7ddde6af350931513acd39e180168d856b7 Mon Sep 17 00:00:00 2001
From: Virginia Czosek <vczosek@gmail.com>
Date: Wed, 6 May 2026 08:43:07 -0700
Subject: [PATCH 5/9] Use relative imports

Co-authored-by: Richard Dinh <1038306+flacoman91@users.noreply.github.com>
---
 src/components/Breadcrumb/breadcrumb.tsx | 2 +-
 src/components/Link/base-link.tsx        | 2 +-
 src/components/Link/link.test.tsx        | 4 ++--
 src/components/Link/link.tsx             | 2 +-
 src/context/dsr-context.tsx              | 4 ++--
 5 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/src/components/Breadcrumb/breadcrumb.tsx b/src/components/Breadcrumb/breadcrumb.tsx
index 5ddbe2011a..7c8f330353 100644
--- a/src/components/Breadcrumb/breadcrumb.tsx
+++ b/src/components/Breadcrumb/breadcrumb.tsx
@@ -3,7 +3,7 @@ import type { HTMLAttributes } from 'react';
 import { Fragment } from 'react';
 import './breadcrumb.scss';
 import { JSXElement } from '../../types/jsx-element';
-import Link from '~/src/components/Link/link';
+import Link from '../Link/link';
 
 export interface BreadcrumbCrumb {
   to: string;
diff --git a/src/components/Link/base-link.tsx b/src/components/Link/base-link.tsx
index 60685bad0c..67bcdb0d62 100644
--- a/src/components/Link/base-link.tsx
+++ b/src/components/Link/base-link.tsx
@@ -1,5 +1,5 @@
 import { ReactNode } from "react";
-import type { JSXElement } from "~/src/types/jsx-element";
+import type { JSXElement } from "../../types/jsx-element";
 
 export interface BaseLinkProperties {
   to: string | undefined;
diff --git a/src/components/Link/link.test.tsx b/src/components/Link/link.test.tsx
index ca51e87678..e6e345da39 100644
--- a/src/components/Link/link.test.tsx
+++ b/src/components/Link/link.test.tsx
@@ -1,9 +1,9 @@
 import '@testing-library/jest-dom';
 import { render, screen } from '@testing-library/react';
 import Link, { LinkText, ListLink } from './link';
-import { DSRContext } from '~/src/context/dsr-context';
+import { DSRContext } from '../../context/dsr-context';
 import { ReactNode } from 'react';
-import type { JSXElement } from "~/src/types/jsx-element";
+import type { JSXElement } from "../../types/jsx-element";
 
 describe('<Link />', () => {
   const linkBaseProperties = {
diff --git a/src/components/Link/link.tsx b/src/components/Link/link.tsx
index 07f4d0268c..5a55bd70e7 100644
--- a/src/components/Link/link.tsx
+++ b/src/components/Link/link.tsx
@@ -2,7 +2,7 @@ import { JSX } from 'react';
 import type { JSXElement } from '../../types/jsx-element';
 import classnames from 'classnames';
 import type { HTMLProps, ReactNode, Ref } from 'react';
-import { useDSRContext } from '~/src/context/dsr-context';
+import { useDSRContext } from '../../context/dsr-context';
 import { Icon } from '../Icon/icon';
 import ListItem from '../List/list-item';
 import './link.scss';
diff --git a/src/context/dsr-context.tsx b/src/context/dsr-context.tsx
index 1e0f5f4140..b634f56f1a 100644
--- a/src/context/dsr-context.tsx
+++ b/src/context/dsr-context.tsx
@@ -1,7 +1,7 @@
 import { createContext, use } from 'react'
 import type { ReactNode } from 'react';
-import { BaseLink } from '~/src/components/Link/base-link';
-import type { BaseLinkProperties } from '~/src/components/Link/base-link';
+import { BaseLink } from '../components/Link/base-link';
+import type { BaseLinkProperties } from '../components/Link/base-link';
 
 
 export interface DSRContextType {

From bbf6a8cccdf015f9ed9d071ee2a8c217c108fe9a Mon Sep 17 00:00:00 2001
From: Virginia Czosek <virginia.czosek@cfpb.gov>
Date: Wed, 6 May 2026 09:57:22 -0700
Subject: [PATCH 6/9] Remove react-router dependency and update DSRContext
 imports and provider interface.

---
 package.json                      |  3 +--
 src/components/Link/link.test.tsx | 15 +++++++--------
 src/context/dsr-context.tsx       |  8 ++++----
 yarn.lock                         |  1 -
 4 files changed, 12 insertions(+), 15 deletions(-)

diff --git a/package.json b/package.json
index cec3e50398..f877c2d1f0 100644
--- a/package.json
+++ b/package.json
@@ -50,8 +50,7 @@
   "peerDependencies": {
     "@cfpb/cfpb-design-system": "5.3.2",
     "react": "^19.2.4",
-    "react-dom": "^19.2.4",
-    "react-router": "^7.14.0"
+    "react-dom": "^19.2.4"
   },
   "devDependencies": {
     "@cfpb/browserslist-config": "^0.0.6",
diff --git a/src/components/Link/link.test.tsx b/src/components/Link/link.test.tsx
index e6e345da39..f9205927fb 100644
--- a/src/components/Link/link.test.tsx
+++ b/src/components/Link/link.test.tsx
@@ -22,9 +22,9 @@ describe('<Link />', () => {
     to,
     children,
     ...others
-  }: CustomLinkProperties): JSXElement | null => {
+  }: CustomLinkProperties): JSXElement => {
     return (
-      <a href={to} {...others} data-testid='link-component-from-context'>
+      <a href={to} {...others} className='link-component-from-context'>
         {children}
       </a>
     );
@@ -106,9 +106,8 @@ describe('<Link />', () => {
         </Link>
       </DSRContext>,
     );
-
-    expect(screen.getByTestId('link-component-from-context')).toBeInTheDocument();
-
+    expect(screen.getByTestId('link-test-id')).toBeInTheDocument();
+    expect(screen.getByTestId('link-test-id')).toHaveClass('link-component-from-context');
   });
 
   it('Context: uses base link component by default', () => {
@@ -117,10 +116,10 @@ describe('<Link />', () => {
           <span data-testid='link-child'>Child</span>
         </Link>,
     );
-
-    expect(screen.queryByTestId('link-component-from-context')).not.toBeInTheDocument();
-
+    expect(screen.getByTestId('link-test-id')).toBeInTheDocument();
+    expect(screen.getByTestId('link-test-id')).not.toHaveClass('link-component-from-context');
   });
+
 });
 
 describe('<LinkText>', () => {
diff --git a/src/context/dsr-context.tsx b/src/context/dsr-context.tsx
index b634f56f1a..c7f5ad3fa3 100644
--- a/src/context/dsr-context.tsx
+++ b/src/context/dsr-context.tsx
@@ -1,11 +1,11 @@
 import { createContext, use } from 'react'
-import type { ReactNode } from 'react';
+import type { ComponentType, ReactNode } from 'react';
 import { BaseLink } from '../components/Link/base-link';
 import type { BaseLinkProperties } from '../components/Link/base-link';
 
 
 export interface DSRContextType {
-  LinkComponent: React.ComponentType<BaseLinkProperties>;
+  LinkComponent: ComponentType<BaseLinkProperties>;
 }
 
 export const DSRContext = createContext<DSRContextType>({
@@ -15,13 +15,13 @@ export const DSRContext = createContext<DSRContextType>({
 export const useDSRContext = () => use(DSRContext);
 
 export interface DSRProviderProperties {
-  LinkComponent: React.ComponentType<BaseLinkProperties> | null;
+  LinkComponent: ComponentType<BaseLinkProperties>;
   children?: ReactNode;
 };
 
 export const DSRProvider = ({ children, LinkComponent }: { 
   children: ReactNode; 
-  LinkComponent: React.ComponentType<BaseLinkProperties>;
+  LinkComponent: ComponentType<BaseLinkProperties>;
 }) => {
   return (
     <DSRContext value={{LinkComponent: LinkComponent}}>
diff --git a/yarn.lock b/yarn.lock
index a02b223390..d39ce0b4b7 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -1305,7 +1305,6 @@ __metadata:
     "@cfpb/cfpb-design-system": 5.3.2
     react: ^19.2.4
     react-dom: ^19.2.4
-    react-router: ^7.14.0
   languageName: unknown
   linkType: soft
 

From ae50f3fca0e3981209cab279592b29f8bc4f70d8 Mon Sep 17 00:00:00 2001
From: Virginia Czosek <virginia.czosek@cfpb.gov>
Date: Mon, 18 May 2026 17:27:51 -0700
Subject: [PATCH 7/9] Add documentation for DSRContext.

---
 src/context/dsr-context.tsx | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/src/context/dsr-context.tsx b/src/context/dsr-context.tsx
index c7f5ad3fa3..ee4d862ea5 100644
--- a/src/context/dsr-context.tsx
+++ b/src/context/dsr-context.tsx
@@ -3,6 +3,31 @@ import type { ComponentType, ReactNode } from 'react';
 import { BaseLink } from '../components/Link/base-link';
 import type { BaseLinkProperties } from '../components/Link/base-link';
 
+/**
+ * 
+ * DSR context allows you to integrate the DSR with a router library 
+ * by specifying a custom component that will be output by the DSR's 
+ * Link component instead of the default anchor element. 
+ * 
+ * Your custom link component will be substituted everywhere the DSR's 
+ * Link component is used, including in the Header, Breadcrumbs, 
+ * and Secondary Navigation components.
+ * 
+ * Example usage with Tanstack Router:
+ * 
+ * rootRoute.tsx:
+ * 
+ * import { createRootRouteWithContext, Link, Outlet } from '@tanstack/react-router'
+ * 
+ * const rootRoute = createRootRouteWithContext<RouterContext>()({
+ *  component: (): JSX.Element => (
+ *    <DSRContext value={{LinkComponent: Link}} >
+ *      <Outlet />
+ *    </DSRContext>
+ *  )
+ * })
+ * 
+ */
 
 export interface DSRContextType {
   LinkComponent: ComponentType<BaseLinkProperties>;

From 1f95799777cd6cc90aff2680daad84ef60a1c579 Mon Sep 17 00:00:00 2001
From: Virginia Czosek <virginia.czosek@cfpb.gov>
Date: Wed, 20 May 2026 10:30:35 -0700
Subject: [PATCH 8/9] Update link stories

---
 src/components/Link/link.stories.tsx | 82 ++++++++++++++++++----------
 1 file changed, 53 insertions(+), 29 deletions(-)

diff --git a/src/components/Link/link.stories.tsx b/src/components/Link/link.stories.tsx
index f819e26ac6..d4845e09cb 100644
--- a/src/components/Link/link.stories.tsx
+++ b/src/components/Link/link.stories.tsx
@@ -1,12 +1,13 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
-import { BrowserRouter } from 'react-router';
 import { expect, within } from 'storybook/test';
-import { Heading, Link, List, ListLink } from '~/src/index';
+import type { JSXElement } from "../../types/jsx-element";
+import { DSRContext, Heading, Link, List, ListLink, type BaseLinkProperties } from '~/src/index';
 
 const meta: Meta<typeof Link> = {
   title: 'Components (Verified)/Links',
   tags: ['autodocs'],
   component: Link,
+  excludeStories: ['CustomLinkComponent']
 };
 
 export default meta;
@@ -15,7 +16,7 @@ type Story = StoryObj<typeof meta>;
 
 const DefaultArguments = {
   args: {
-    href: '#',
+    to: '#',
     children: 'Link Text',
   },
 };
@@ -23,19 +24,19 @@ const DefaultArguments = {
 export const Inline: Story = {
   render: () => (
     <p>
-      Here&apos;s the default <Link href='/#' label='inline link' /> style.
+      Here&apos;s the default <Link to='/#' label='inline link' /> style.
     </p>
   ),
 };
 
 export const Standalone: Story = {
   render: (arguments_) => (
-    <Link {...arguments_} href='/#' isJump label='Standalone link' />
+    <Link {...arguments_} to='/#' isJump label='Standalone link' />
   ),
   play: async ({ canvasElement }) => {
     const canvas = within(canvasElement);
     const link = canvas.getByRole('link', { name: /standalone link/i });
-    await expect(link).toHaveAttribute('href', '/#');
+    await expect(link).toHaveAttribute('to', '/#');
   },
 };
 
@@ -50,13 +51,13 @@ export const WithIcon: Story = {
       <p>
         The document icon should emphasize a link that contains a{' '}
         <Link
-          href={DefaultArguments.args.href}
+          to={DefaultArguments.args.to}
           label='file or document'
           iconRight='download'
         />
         . The external link icon is used to emphasize a link to a{' '}
         <Link
-          href={DefaultArguments.args.href}
+          to={DefaultArguments.args.to}
           label='non-CFPB webpage'
           iconRight='external-link'
         />
@@ -66,7 +67,7 @@ export const WithIcon: Story = {
       <p>
         <Link
           isJump
-          href='https://www.example.com'
+          to='https://www.example.com'
           iconLeft='left'
           label='Go back'
         />
@@ -74,7 +75,7 @@ export const WithIcon: Story = {
       <p>
         <Link
           isJump
-          href='https://www.example.com'
+          to='https://www.example.com'
           label='Continue'
           iconRight='right'
         />
@@ -82,7 +83,7 @@ export const WithIcon: Story = {
       <p>
         <Link
           isJump
-          href='https://www.example.com'
+          to='https://www.example.com'
           label='External link'
           iconRight='external-link'
         />
@@ -90,7 +91,7 @@ export const WithIcon: Story = {
       <p>
         <Link
           isJump
-          href='https://www.example.com'
+          to='https://www.example.com'
           label='Document or file'
           iconRight='document'
         />
@@ -106,9 +107,9 @@ export const Listlink: Story = {
   },
   render: () => (
     <List isLinks>
-      <ListLink href='/#' label='List item 1' />
-      <ListLink href='/#' label='List item 2' />
-      <ListLink href='/#' label='List item 3' />
+      <ListLink to='/#' label='List item 1' />
+      <ListLink to='/#' label='List item 2' />
+      <ListLink to='/#' label='List item 3' />
     </List>
   ),
 };
@@ -117,22 +118,45 @@ export const Destructive: Story = {
   args: {
     ...DefaultArguments.args,
   },
-  render: () => <Link href='/#' type='destructive' label='Destructive link' />,
+  render: () => <Link to='/#' type='destructive' label='Destructive link' />,
 };
 
-export const LinkWithReactRouterLink: Story = {
-  name: 'Link using React Router Link',
-  parameters: {
-    docs: {
-      description: {
-        story:
-          'See [React Router Link docs](https://reactrouter.com/api/components/Link) for usage information',
-      },
-    },
-  },
+const CustomLinkComponent = ({
+  to,
+  children,
+  ...others
+}: BaseLinkProperties): JSXElement | null => {
+  return (
+    <a href={to} {...others} data-link-component='custom'>
+      {children}
+    </a>
+  );
+};
+
+/**
+ * You can configure the DSR to use a router library's link component by wrapping your app
+ * in the DSRContext provider and setting a `LinkComponent` value. 
+ * Your custom link component will be substituted for the default anchor element 
+ * everywhere the DSR's Link component is used.
+ *  
+ * Example usage:
+ * 
+ *  \<DSRContext value={{LinkComponent: YourRouterLinkComponent}} >
+ *    App content
+ *  \</DSRContext>
+ */
+export const LinkWithCustomLinkComponent: Story = {
+  name: 'Link using custom component',
+  decorators: [
+    (Story) => (
+      <DSRContext value={{ LinkComponent: CustomLinkComponent }}>
+        <Story />
+      </DSRContext>
+    ),
+  ],
   render: () => (
-    <BrowserRouter>
-      <Link href='/#' label='Link using React Router Link' isRouterLink />
-    </BrowserRouter>
+      <Link to='/#' label='Link using custom link component' />
   ),
 };
+
+

From 4444b40e9f92c1f9656ed2d013c5f0c93388e344 Mon Sep 17 00:00:00 2001
From: Virginia Czosek <virginia.czosek@cfpb.gov>
Date: Wed, 20 May 2026 14:14:32 -0700
Subject: [PATCH 9/9] Update story description

---
 src/components/Link/link.stories.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/components/Link/link.stories.tsx b/src/components/Link/link.stories.tsx
index d4845e09cb..169eb442ff 100644
--- a/src/components/Link/link.stories.tsx
+++ b/src/components/Link/link.stories.tsx
@@ -136,7 +136,7 @@ const CustomLinkComponent = ({
 /**
  * You can configure the DSR to use a router library's link component by wrapping your app
  * in the DSRContext provider and setting a `LinkComponent` value. 
- * Your custom link component will be substituted for the default anchor element 
+ * Your custom link component will be output instead of the default anchor element 
  * everywhere the DSR's Link component is used.
  *  
  * Example usage: