Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix: adopt XDSLinkProvider across all link-rendering components (#1906)

Cindy Zhang25f44e09bed2
diff --git a/CLAUDE.md b/CLAUDE.md
index 594718c149..815a4d3694 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -111,6 +111,7 @@ Documentation lives in two places:
|PATTERN: CSS fallback values -> stylex.firstThatWorks() (not manual fallback)
|PATTERN: dynamic/runtime values -> stylex.create({ s: (val) => ({ prop: val }) }) (not inline styles)
|PATTERN: conditional styles -> stylex.props(condition && styles.x) (not className toggling)
+|PATTERN: link elements -> useXDSLinkComponent() (not hardcoded <a>). Consumers swap via XDSLinkProvider for framework routers (Next.js, React Router)
|VERIFY: node internal/stylex-capabilities/scan.mjs
<!-- STYLEX-CAPS:END -->
diff --git a/internal/eslint-plugin-xds/index.js b/internal/eslint-plugin-xds/index.js
index 3526948ffa..3c47612d4a 100644
--- a/internal/eslint-plugin-xds/index.js
+++ b/internal/eslint-plugin-xds/index.js
@@ -18,6 +18,7 @@ import docblockExampleFormatRule from './docblock-example-format.js';
import noStylexNullOverrideRule from './no-stylex-null-override.js';
import noReactIntrospectionRule from './no-react-introspection.js';
import noClassnameClobberRule from './no-classname-clobber.js';
+import noHardcodedAnchorRule from './no-hardcoded-anchor.js';
// =============================================================================
// Rule: no-hardcoded-styles
@@ -224,6 +225,7 @@ const plugin = {
'no-stylex-null-override': noStylexNullOverrideRule,
'no-react-introspection': noReactIntrospectionRule,
'no-classname-clobber': noClassnameClobberRule,
+ 'no-hardcoded-anchor': noHardcodedAnchorRule,
},
configs: {},
};
@@ -241,6 +243,7 @@ plugin.configs.strict = {
'@xds/no-stylex-null-override': 'error',
'@xds/no-react-introspection': 'error',
'@xds/no-classname-clobber': 'error',
+ '@xds/no-hardcoded-anchor': 'error',
},
};
@@ -257,6 +260,7 @@ plugin.configs.recommended = {
'@xds/no-stylex-null-override': 'warn',
'@xds/no-react-introspection': 'error',
'@xds/no-classname-clobber': 'error',
+ '@xds/no-hardcoded-anchor': 'warn',
},
};
diff --git a/internal/eslint-plugin-xds/no-hardcoded-anchor.js b/internal/eslint-plugin-xds/no-hardcoded-anchor.js
new file mode 100644
index 0000000000..d863524128
--- /dev/null
+++ b/internal/eslint-plugin-xds/no-hardcoded-anchor.js
@@ -0,0 +1,94 @@
+/**
+ * @file no-hardcoded-anchor.js
+ * @description Disallow hardcoded `<a>` elements in XDS core components.
+ *
+ * Components that render links should use `useXDSLinkComponent()` to resolve
+ * the link element, allowing consumers to swap in their framework's router
+ * (Next.js Link, React Router Link, etc.) via `XDSLinkProvider`.
+ *
+ * This rule catches `<a>` JSX elements and suggests using the link provider
+ * pattern instead. It allows `<a>` in a few known cases:
+ * - Test files (*.test.tsx)
+ * - The Link infrastructure itself (XDSLink.tsx, XDSLinkProvider.tsx)
+ * - In-page anchors (href starting with #)
+ *
+ * Bad:
+ * <a href={href} className={styles.link}>{children}</a>
+ *
+ * Good:
+ * const LinkComponent = useXDSLinkComponent();
+ * <LinkComponent href={href} className={styles.link}>{children}</LinkComponent>
+ */
+
+const ALLOWED_FILES = [
+ 'XDSLink.tsx',
+ 'XDSLinkProvider.tsx',
+ 'XDSLinkContext.ts',
+ 'useXDSLinkComponent.ts',
+ 'types.ts',
+];
+
+const rule = {
+ meta: {
+ type: 'suggestion',
+ docs: {
+ description:
+ 'Disallow hardcoded <a> elements — use useXDSLinkComponent() for router integration',
+ category: 'Best Practices',
+ recommended: true,
+ },
+ messages: {
+ hardcodedAnchor:
+ 'Hardcoded <a> element. Use `useXDSLinkComponent()` to resolve the link component, ' +
+ 'so consumers can swap in their framework router via XDSLinkProvider. ' +
+ 'See: packages/core/src/Link/useXDSLinkComponent.ts',
+ },
+ schema: [],
+ },
+ create(context) {
+ const filename = context.filename;
+
+ // Skip test files
+ if (filename.includes('.test.') || filename.includes('.stories.')) {
+ return {};
+ }
+
+ // Skip the Link infrastructure files themselves
+ if (ALLOWED_FILES.some(f => filename.endsWith(f))) {
+ return {};
+ }
+
+ return {
+ JSXOpeningElement(node) {
+ // Only flag <a> elements
+ if (node.name?.type !== 'JSXIdentifier' || node.name.name !== 'a') {
+ return;
+ }
+
+ // Allow in-page anchors (href="#..." or href={`#...`})
+ const hrefAttr = node.attributes.find(
+ attr =>
+ attr.type === 'JSXAttribute' &&
+ attr.name?.name === 'href' &&
+ (
+ // String literal: href="#section"
+ (attr.value?.type === 'Literal' &&
+ typeof attr.value.value === 'string' &&
+ attr.value.value.startsWith('#')) ||
+ // Expression: href={`#${id}`}
+ (attr.value?.type === 'JSXExpressionContainer' &&
+ attr.value.expression?.type === 'TemplateLiteral' &&
+ attr.value.expression.quasis?.[0]?.value?.raw?.startsWith('#'))
+ ),
+ );
+ if (hrefAttr) {
+ return;
+ }
+
+ context.report({node, messageId: 'hardcodedAnchor'});
+ },
+ };
+ },
+};
+
+export default rule;
diff --git a/internal/eslint-plugin-xds/no-hardcoded-anchor.test.mjs b/internal/eslint-plugin-xds/no-hardcoded-anchor.test.mjs
new file mode 100644
index 0000000000..34dadb54a7
--- /dev/null
+++ b/internal/eslint-plugin-xds/no-hardcoded-anchor.test.mjs
@@ -0,0 +1,53 @@
+/**
+ * @file no-hardcoded-anchor.test.mjs
+ * @description Tests for the no-hardcoded-anchor ESLint rule.
+ */
+
+import {describe, it} from 'vitest';
+import {RuleTester} from 'eslint';
+import tseslint from 'typescript-eslint';
+import noHardcodedAnchorRule from './no-hardcoded-anchor.js';
+
+const ruleTester = new RuleTester({
+ languageOptions: {
+ parser: tseslint.parser,
+ parserOptions: {
+ ecmaFeatures: {jsx: true},
+ },
+ },
+});
+
+describe('no-hardcoded-anchor', () => {
+ it('passes the RuleTester', () => {
+ ruleTester.run('no-hardcoded-anchor', noHardcodedAnchorRule, {
+ valid: [
+ // Using LinkComponent (the pattern we want)
+ {code: '<LinkComponent href="/foo">text</LinkComponent>'},
+ // In-page anchor with # href is allowed
+ {code: '<a href="#section">Jump</a>'},
+ // In-page anchor with template literal # href is allowed
+ {code: '<a href={`#${id}`}>Jump</a>'},
+ // Non-anchor elements are fine
+ {code: '<button onClick={fn}>click</button>'},
+ {code: '<div>content</div>'},
+ ],
+ invalid: [
+ // Hardcoded <a> with dynamic href
+ {
+ code: '<a href={href}>link</a>',
+ errors: [{messageId: 'hardcodedAnchor'}],
+ },
+ // Hardcoded <a> with string href
+ {
+ code: '<a href="/foo">link</a>',
+ errors: [{messageId: 'hardcodedAnchor'}],
+ },
+ // Hardcoded <a> with no href
+ {
+ code: '<a onClick={fn}>link</a>',
+ errors: [{messageId: 'hardcodedAnchor'}],
+ },
+ ],
+ });
+ });
+});
diff --git a/packages/cli/docs/principles.doc.dense.mjs b/packages/cli/docs/principles.doc.dense.mjs
index c6f63f321f..77f3643c18 100644
--- a/packages/cli/docs/principles.doc.dense.mjs
+++ b/packages/cli/docs/principles.doc.dense.mjs
@@ -5,7 +5,7 @@ export const docsDense = {
sections: [
{ title: 'Rules', content: [{ type: 'list', items: ['use XDS components', 'StyleX for styling', 'semantic tokens only', 'CSS vars for colors', 'controlled form inputs'] }] },
{ title: 'xstyle prop', content: [{ type: 'prose', text: 'xstyle accepts inline obj, stylex.create, or CSS class string.' }, null, null, null, { type: 'list', items: ['1-2 props: inline', '3+ props: stylex.create', 'pseudo-classes: stylex.create required', ':hover needs @media (hover: hover)'] }] },
- { title: 'Anti-Patterns', content: [{ type: 'list', items: ['no inline styles on raw elements', 'no hardcoded colors', 'no hardcoded spacing', 'read docs before inventing props'] }] },
+ { title: 'Anti-Patterns', content: [{ type: 'list', items: ['no inline styles on raw elements', 'no hardcoded colors', 'no hardcoded spacing', 'no hardcoded <a> — use useXDSLinkComponent()', 'read docs before inventing props'] }] },
{ title: 'StyleX', content: [null] },
{ title: 'Token Quick Ref', content: [{ type: 'prose', text: 'see xds docs tokens' }, null] },
],
diff --git a/packages/cli/docs/principles.doc.mjs b/packages/cli/docs/principles.doc.mjs
index 358eda25a9..c03ebd6df6 100644
--- a/packages/cli/docs/principles.doc.mjs
+++ b/packages/cli/docs/principles.doc.mjs
@@ -80,6 +80,7 @@ const overrides = stylex.create({
'Inline styles on raw elements. Use xstyle on XDS components',
'Hardcoded colors (#fff). Use var(--color-*)',
'Hardcoded spacing (16px). Use spacing tokens or var(--spacing-*)',
+ 'Hardcoded <a> elements. Use useXDSLinkComponent() so consumers can swap in their framework router via XDSLinkProvider',
'Inventing props. Read component docs first',
],
},
diff --git a/packages/core/src/ClickableCard/XDSClickableCard.tsx b/packages/core/src/ClickableCard/XDSClickableCard.tsx
index cb19e06438..de28b61a98 100644
--- a/packages/core/src/ClickableCard/XDSClickableCard.tsx
+++ b/packages/core/src/ClickableCard/XDSClickableCard.tsx
@@ -42,6 +42,7 @@ import {XDSCard} from '../Card/XDSCard';
import type {XDSCardVariant} from '../Card/XDSCard';
import {useClickableContainer} from '../hooks/useClickableContainer';
import type {XDSBaseProps} from '../XDSBaseProps';
+import {useXDSLinkComponent} from '../Link/useXDSLinkComponent';
// =============================================================================
// Styles — only the interactive layer, Card handles everything else
@@ -228,6 +229,7 @@ export function XDSClickableCard({
}: XDSClickableCardProps) {
const containerRef = useRef<HTMLDivElement | null>(null);
const interactiveRef = useRef<HTMLElement | null>(null);
+ const LinkComponent = useXDSLinkComponent();
const {onClick, onMouseUp} = useClickableContainer({
containerRef,
@@ -280,7 +282,7 @@ export function XDSClickableCard({
onMouseUp={!isDisabled ? handleMouseUp : undefined}
{...props}>
{isLink ? (
- <a
+ <LinkComponent
ref={interactiveRef as React.Ref<HTMLAnchorElement>}
href={href}
target={target}
diff --git a/packages/core/src/Link/Link.doc.mjs b/packages/core/src/Link/Link.doc.mjs
index 086e0d538a..79d728640e 100644
--- a/packages/core/src/Link/Link.doc.mjs
+++ b/packages/core/src/Link/Link.doc.mjs
@@ -79,7 +79,8 @@ export const docs = {
{
name: 'XDSLinkProvider',
description:
- 'Provider that sets the default link component for all XDS link components in the subtree.',
+ 'Provider that sets the default link component for all XDS link-rendering components in the subtree. ' +
+ 'Wrap your app root to replace native <a> elements with your framework router (Next.js Link, React Router Link, etc.).',
props: [
{
name: 'component',
diff --git a/packages/core/src/List/XDSListItem.tsx b/packages/core/src/List/XDSListItem.tsx
index b98af980dd..8bab4e70f0 100644
--- a/packages/core/src/List/XDSListItem.tsx
+++ b/packages/core/src/List/XDSListItem.tsx
@@ -29,6 +29,7 @@ import {
import type {XDSBaseProps} from '../XDSBaseProps';
import {XDSListContext} from './XDSListContext';
import {xdsClassName, mergeProps} from '../utils';
+import {useXDSLinkComponent} from '../Link/useXDSLinkComponent';
// =============================================================================
// Types
@@ -343,6 +344,7 @@ export function XDSListItem({
...restProps
}: XDSListItemProps) {
const ctx = useContext(XDSListContext);
+ const LinkComponent = useXDSLinkComponent();
const density = ctx?.density ?? 'balanced';
const hasDividers = ctx?.hasDividers ?? false;
const listStyle = ctx?.listStyle ?? 'none';
@@ -386,7 +388,7 @@ export function XDSListItem({
)}
{href != null ? (
- <a
+ <LinkComponent
href={href}
target={target}
aria-disabled={isDisabled || undefined}
@@ -396,7 +398,7 @@ export function XDSListItem({
isDisabled && styles.disabledContent,
)}>
{labelAndDescription}
- </a>
+ </LinkComponent>
) : onClick != null ? (
<button
type="button"
diff --git a/packages/core/src/Markdown/XDSMarkdown.tsx b/packages/core/src/Markdown/XDSMarkdown.tsx
index a84adb5efa..363cac2749 100644
--- a/packages/core/src/Markdown/XDSMarkdown.tsx
+++ b/packages/core/src/Markdown/XDSMarkdown.tsx
@@ -30,6 +30,8 @@ import {XDSList} from '../List/XDSList';
import {XDSListItem} from '../List/XDSListItem';
import {xdsClassName, mergeProps} from '../utils';
import {useXDSStreamingText} from '../hooks/useXDSStreamingText';
+import {useXDSLinkComponent} from '../Link/useXDSLinkComponent';
+import type {XDSLinkComponentType} from '../Link/types';
import {
parseMarkdown,
parseMarkdownIncremental,
@@ -611,6 +613,7 @@ function renderInline(
onLinkClick: XDSMarkdownProps['onLinkClick'] | undefined,
cursor: StreamingCursor,
citationCtx: CitationContext | null,
+ linkComponent: XDSLinkComponentType = 'a',
): React.ReactNode {
switch (node.type) {
case 'text':
@@ -619,7 +622,7 @@ function renderInline(
return (
<strong key={index} {...stylex.props(styles.bold)}>
{node.children.map((c, i) =>
- renderInline(c, i, onLinkClick, cursor, citationCtx),
+ renderInline(c, i, onLinkClick, cursor, citationCtx, linkComponent),
)}
</strong>
);
@@ -627,7 +630,7 @@ function renderInline(
return (
<em key={index}>
{node.children.map((c, i) =>
- renderInline(c, i, onLinkClick, cursor, citationCtx),
+ renderInline(c, i, onLinkClick, cursor, citationCtx, linkComponent),
)}
</em>
);
@@ -635,7 +638,7 @@ function renderInline(
return (
<del key={index} {...stylex.props(styles.strikethrough)}>
{node.children.map((c, i) =>
- renderInline(c, i, onLinkClick, cursor, citationCtx),
+ renderInline(c, i, onLinkClick, cursor, citationCtx, linkComponent),
)}
</del>
);
@@ -661,7 +664,7 @@ function renderInline(
return (
<span key={index}>
{node.children.map((c, i) =>
- renderInline(c, i, onLinkClick, cursor, citationCtx),
+ renderInline(c, i, onLinkClick, cursor, citationCtx, linkComponent),
)}
</span>
);
@@ -675,8 +678,12 @@ function renderInline(
}
}
: undefined;
+ // Use linkComponent for internal links, native <a> for external links.
+ // Framework routers (Next.js, React Router) handle internal navigation;
+ // external links with target="_blank" should use a plain anchor.
+ const LinkTag = isExternal ? 'a' : linkComponent;
return (
- <a
+ <LinkTag
key={index}
href={safeHref}
onClick={handleClick}
@@ -685,9 +692,9 @@ function renderInline(
: {})}
{...stylex.props(styles.link)}>
{node.children.map((c, i) =>
- renderInline(c, i, onLinkClick, cursor, citationCtx),
+ renderInline(c, i, onLinkClick, cursor, citationCtx, linkComponent),
)}
- </a>
+ </LinkTag>
);
}
case 'image': {
@@ -835,6 +842,7 @@ function renderBlock(
citationCtx: CitationContext | null,
contentWidthValue: string | null,
contentAlign: 'start' | 'center',
+ linkComponent: XDSLinkComponentType = 'a',
): React.ReactNode {
const spacing = getElementSpacing(node, density);
const isFirst = index === 0;
@@ -867,7 +875,7 @@ function renderBlock(
isLast && styles.noMarginBlockEnd,
)}>
{node.children.map((c, i) =>
- renderInline(c, i, onLinkClick, cursor, citationCtx),
+ renderInline(c, i, onLinkClick, cursor, citationCtx, linkComponent),
)}
</Tag>
);
@@ -888,7 +896,7 @@ function renderBlock(
isLast && styles.noMarginBlockEnd,
)}>
{node.children.map((c, i) =>
- renderInline(c, i, onLinkClick, cursor, citationCtx),
+ renderInline(c, i, onLinkClick, cursor, citationCtx, linkComponent),
)}
</p>
);
@@ -948,6 +956,7 @@ function renderBlock(
citationCtx,
contentWidthValue,
contentAlign,
+ linkComponent,
),
)}
</blockquote>
@@ -991,7 +1000,7 @@ function renderBlock(
const label = isInline ? (
<>
{firstChild.children.map((c, j) =>
- renderInline(c, j, onLinkClick, cursor, citationCtx),
+ renderInline(c, j, onLinkClick, cursor, citationCtx, linkComponent),
)}
</>
) : (
@@ -1008,6 +1017,7 @@ function renderBlock(
citationCtx,
contentWidthValue,
contentAlign,
+ linkComponent,
),
)}
</>
@@ -1070,7 +1080,7 @@ function renderBlock(
const label = isInline ? (
<>
{firstChild.children.map((c, j) =>
- renderInline(c, j, onLinkClick, cursor, citationCtx),
+ renderInline(c, j, onLinkClick, cursor, citationCtx, linkComponent),
)}
</>
) : (
@@ -1087,6 +1097,7 @@ function renderBlock(
citationCtx,
contentWidthValue,
contentAlign,
+ linkComponent,
),
)}
</>
@@ -1145,7 +1156,7 @@ function renderBlock(
alignStyle(node.alignments[i]),
)}>
{h.children.map((c, j) =>
- renderInline(c, j, onLinkClick, cursor, citationCtx),
+ renderInline(c, j, onLinkClick, cursor, citationCtx, linkComponent),
)}
</th>
))}
@@ -1163,7 +1174,7 @@ function renderBlock(
alignStyle(node.alignments[j]),
)}>
{cell.children.map((c, k) =>
- renderInline(c, k, onLinkClick, cursor, citationCtx),
+ renderInline(c, k, onLinkClick, cursor, citationCtx, linkComponent),
)}
</td>
));
@@ -1253,6 +1264,7 @@ export function XDSMarkdown({
style,
'data-testid': testId,
}: XDSMarkdownProps): React.ReactElement {
+ const LinkComponent = useXDSLinkComponent();
// Derive the set of source IDs for the parser (stable across renders when sources don't change)
const sourceIds = useMemo(
() => (sources ? new Set(Object.keys(sources)) : undefined),
@@ -1326,6 +1338,7 @@ export function XDSMarkdown({
: contentWidth
: null,
contentAlign,
+ LinkComponent,
),
)}
</div>
diff --git a/packages/core/src/NavMenu/XDSNavMenuItem.tsx b/packages/core/src/NavMenu/XDSNavMenuItem.tsx
index 4b4fceaf28..f8d99d21b1 100644
--- a/packages/core/src/NavMenu/XDSNavMenuItem.tsx
+++ b/packages/core/src/NavMenu/XDSNavMenuItem.tsx
@@ -25,6 +25,7 @@ import {
} from '../theme/tokens.stylex';
import {xdsClassName, mergeProps} from '../utils';
import {useXDSNavMenuContext} from './XDSNavMenuContext';
+import {useXDSLinkComponent} from '../Link/useXDSLinkComponent';
const styles = stylex.create({
root: {
@@ -120,7 +121,8 @@ export function XDSNavMenuItem({
ctx?.closeMenu();
}, [isDisabled, onClick, ctx]);
- const Element = href ? 'a' : 'div';
+ const LinkComponent = useXDSLinkComponent();
+ const Element = href ? LinkComponent : 'div';
return (
<Element
diff --git a/packages/core/src/Token/XDSToken.tsx b/packages/core/src/Token/XDSToken.tsx
index 8b432e11b2..dd10c41ea2 100644
--- a/packages/core/src/Token/XDSToken.tsx
+++ b/packages/core/src/Token/XDSToken.tsx
@@ -29,6 +29,7 @@ import {
} from '../theme/tokens.stylex';
import {XDSIcon} from '../Icon';
import {xdsClassName, mergeProps} from '../utils';
+import {useXDSLinkComponent} from '../Link/useXDSLinkComponent';
// =============================================================================
// Types
@@ -340,6 +341,7 @@ export function XDSToken({
'data-testid': testId,
ref,
}: XDSTokenProps) {
+ const LinkComponent = useXDSLinkComponent();
const content = (
<>
{icon}
@@ -372,7 +374,7 @@ export function XDSToken({
if (href != null) {
return (
- <a
+ <LinkComponent
ref={ref as React.Ref<HTMLAnchorElement>}
href={href}
aria-disabled={isDisabled || undefined}
@@ -391,7 +393,7 @@ export function XDSToken({
style,
)}>
{content}
- </a>
+ </LinkComponent>
);
}
diff --git a/packages/core/src/TopNav/XDSTopNavMegaMenuFeaturedCard.tsx b/packages/core/src/TopNav/XDSTopNavMegaMenuFeaturedCard.tsx
index 5dd22b888e..d00b9b362c 100644
--- a/packages/core/src/TopNav/XDSTopNavMegaMenuFeaturedCard.tsx
+++ b/packages/core/src/TopNav/XDSTopNavMegaMenuFeaturedCard.tsx
@@ -25,6 +25,7 @@ import {
fontWeightVars,
} from '../theme/tokens.stylex';
import {xdsClassName, mergeProps} from '../utils';
+import {useXDSLinkComponent} from '../Link/useXDSLinkComponent';
// =============================================================================
// Styles
@@ -126,6 +127,7 @@ export function XDSTopNavMegaMenuFeaturedCard({
linkHref,
children,
}: XDSTopNavMegaMenuFeaturedCardProps) {
+ const LinkComponent = useXDSLinkComponent();
return (
<div
{...mergeProps(
@@ -141,9 +143,9 @@ export function XDSTopNavMegaMenuFeaturedCard({
<span {...stylex.props(styles.description)}>{description}</span>
)}
{linkLabel && linkHref && (
- <a href={linkHref} {...stylex.props(styles.link)}>
+ <LinkComponent href={linkHref} {...stylex.props(styles.link)}>
{linkLabel} →
- </a>
+ </LinkComponent>
)}
{children}
</div>
diff --git a/packages/core/src/TopNav/XDSTopNavMenu.tsx b/packages/core/src/TopNav/XDSTopNavMenu.tsx
index a72ae5eb2b..0f20c1294c 100644
--- a/packages/core/src/TopNav/XDSTopNavMenu.tsx
+++ b/packages/core/src/TopNav/XDSTopNavMenu.tsx
@@ -29,6 +29,7 @@ import {navItemStyles} from '../NavItem/navItemStyles.stylex';
import {useTopNavSlot} from './TopNavContext';
import {useXDSTopNavRenderMode} from './XDSTopNavRenderContext';
import {useXDSAppShellMobile} from '../AppShell/XDSAppShellMobileContext';
+import {useXDSLinkComponent} from '../Link/useXDSLinkComponent';
import {
colorVars,
spacingVars,
@@ -319,6 +320,7 @@ export function XDSTopNavMenu({
}: XDSTopNavMenuProps) {
const renderMode = useXDSTopNavRenderMode();
const {closeMobileNav} = useXDSAppShellMobile();
+ const LinkComponent = useXDSLinkComponent();
const [drawerExpanded, setDrawerExpanded] = useState(false);
const menuId = useId();
@@ -354,10 +356,10 @@ export function XDSTopNavMenu({
)}>
<div {...stylex.props(drawerStyles.itemsInner)}>
{items.map((item, i) => (
- <a
+ <LinkComponent
key={i}
href={item.href}
- onClick={e => {
+ onClick={(e: React.MouseEvent) => {
item.onClick?.();
closeMobileNav();
}}
@@ -375,7 +377,7 @@ export function XDSTopNavMenu({
</span>
)}
</span>
- </a>
+ </LinkComponent>
))}
</div>
</div>
diff --git a/packages/core/src/TreeList/XDSTreeListItem.tsx b/packages/core/src/TreeList/XDSTreeListItem.tsx
index 201bc937cd..ead743a415 100644
--- a/packages/core/src/TreeList/XDSTreeListItem.tsx
+++ b/packages/core/src/TreeList/XDSTreeListItem.tsx
@@ -24,6 +24,7 @@ import {
} from '../theme/tokens.stylex';
import {getIcon} from '../Icon/globalIconRegistry';
import {xdsClassName, mergeProps} from '../utils';
+import {useXDSLinkComponent} from '../Link/useXDSLinkComponent';
import {XDSTreeListBranches} from './XDSTreeListBranches';
import type {XDSTreeListDensity} from './XDSTreeListTypes';
@@ -274,6 +275,7 @@ export function XDSTreeListItem({
}: XDSTreeListItemInternalProps) {
const labelId = useId();
const descriptionId = useId();
+ const LinkComponent = useXDSLinkComponent();
const isInteractive = onClick != null || href != null;
const handleToggle = useMemo(
@@ -356,7 +358,7 @@ export function XDSTreeListItem({
<span {...stylex.props(styles.startContent)}>{startContent}</span>
)}
{href != null ? (
- <a
+ <LinkComponent
href={href}
target={target}
aria-disabled={isDisabled || undefined}
@@ -365,7 +367,7 @@ export function XDSTreeListItem({
tabIndex={isDisabled ? -1 : undefined}
{...stylex.props(styles.invisibleAnchor)}>
{labelAndDescription}
- </a>
+ </LinkComponent>
) : onClick != null ? (
<button
type="button"
diff --git a/packages/core/src/hooks/useClickableContainer.ts b/packages/core/src/hooks/useClickableContainer.ts
index f9682c5427..5395e2f91f 100644
--- a/packages/core/src/hooks/useClickableContainer.ts
+++ b/packages/core/src/hooks/useClickableContainer.ts
@@ -165,6 +165,10 @@ export function useClickableContainer({
target === '_blank' || event.ctrlKey || event.metaKey;
if (shouldOpenNewTab) {
window.open(href, '_blank', 'noopener');
+ } else if (interactiveRef?.current) {
+ // Proxy click to the sr-only link so the framework link component
+ // handles navigation (client-side transitions in Next.js, etc.).
+ interactiveRef.current.click();
} else {
window.location.href = href;
}