Skip to content

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

TypeScript

fix(core): disabled TopNav items no longer navigate; Outline aria-current location (#4368)

Baraa Hamodi232fe0fc8eea
diff --git a/.changeset/a11y-topnav-disabled-href.md b/.changeset/a11y-topnav-disabled-href.md
new file mode 100644
index 0000000000..2f57cab5b0
--- /dev/null
+++ b/.changeset/a11y-topnav-disabled-href.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] TopNav: disabled TopNavItems now render href-less anchors so they no longer navigate or fire clicks, and Outline's active item uses aria-current="location"
+@bhamodi
diff --git a/packages/core/src/Outline/Outline.test.tsx b/packages/core/src/Outline/Outline.test.tsx
index 1536bb9db2..18f9ece672 100644
--- a/packages/core/src/Outline/Outline.test.tsx
+++ b/packages/core/src/Outline/Outline.test.tsx
@@ -86,7 +86,7 @@ describe('Outline', () => {
render(<Outline items={items} activeId="install" />);
expect(screen.getByRole('link', {name: 'Installation'})).toHaveAttribute(
'aria-current',
- 'true',
+ 'location',
);
expect(
screen.getByRole('link', {name: 'Introduction'}),
@@ -111,7 +111,7 @@ describe('Outline', () => {
// so it has not moved to the clicked item yet.
expect(
screen.getByRole('link', {name: 'Installation'}),
- ).not.toHaveAttribute('aria-current', 'true');
+ ).not.toHaveAttribute('aria-current', 'location');
// When the scroll settles, the indicator lands on the clicked item.
act(() => {
@@ -120,7 +120,7 @@ describe('Outline', () => {
expect(onActiveIdChange).toHaveBeenCalledWith('install');
expect(screen.getByRole('link', {name: 'Installation'})).toHaveAttribute(
'aria-current',
- 'true',
+ 'location',
);
document.body.removeChild(target);
@@ -224,7 +224,7 @@ describe('Outline', () => {
expect(screen.getByRole('link', {name: 'Introduction'})).toHaveAttribute(
'aria-current',
- 'true',
+ 'location',
);
// Controlled active id is driven entirely by the prop.
@@ -237,7 +237,7 @@ describe('Outline', () => {
);
expect(screen.getByRole('link', {name: 'API'})).toHaveAttribute(
'aria-current',
- 'true',
+ 'location',
);
expect(
screen.getByRole('link', {name: 'Introduction'}),
@@ -277,7 +277,7 @@ describe('Outline', () => {
expect(screen.getByRole('link', {name: 'Installation'})).toHaveAttribute(
'aria-current',
- 'true',
+ 'location',
);
expect(onActiveIdChange).toHaveBeenCalledWith('install');
@@ -493,7 +493,7 @@ describe('Outline keyboard navigation', () => {
expect(onNavigateEnd).toHaveBeenCalledTimes(1);
expect(screen.getByRole('link', {name: 'Installation'})).toHaveAttribute(
'aria-current',
- 'true',
+ 'location',
);
cleanup();
@@ -764,7 +764,7 @@ describe('Outline scroll scoping', () => {
expect(onNavigateEnd).toHaveBeenCalledWith('install');
expect(screen.getByRole('link', {name: 'Installation'})).toHaveAttribute(
'aria-current',
- 'true',
+ 'location',
);
cleanup();
@@ -797,7 +797,7 @@ describe('Outline scroll scoping', () => {
// has not reached it, so `intro` stays active.
expect(screen.getByRole('link', {name: 'Introduction'})).toHaveAttribute(
'aria-current',
- 'true',
+ 'location',
);
rerender(<Outline items={items} offset={64} />);
@@ -806,7 +806,7 @@ describe('Outline scroll scoping', () => {
});
expect(screen.getByRole('link', {name: 'Installation'})).toHaveAttribute(
'aria-current',
- 'true',
+ 'location',
);
cleanup();
@@ -930,7 +930,7 @@ describe('Outline scroll scoping', () => {
expect(screen.getByRole('link', {name: 'Installation'})).toHaveAttribute(
'aria-current',
- 'true',
+ 'location',
);
expect(screen.getByRole('link', {name: 'API'})).not.toHaveAttribute(
'aria-current',
@@ -981,7 +981,7 @@ describe('Outline scroll scoping', () => {
expect(screen.getByRole('link', {name: 'Installation'})).toHaveAttribute(
'aria-current',
- 'true',
+ 'location',
);
pane.remove();
diff --git a/packages/core/src/Outline/Outline.tsx b/packages/core/src/Outline/Outline.tsx
index 7ee65714d0..7b00517732 100644
--- a/packages/core/src/Outline/Outline.tsx
+++ b/packages/core/src/Outline/Outline.tsx
@@ -372,7 +372,7 @@ export function Outline({
}
const links = Array.from(list.querySelectorAll<HTMLElement>('a[href]'));
const active = links.find(
- link => link.getAttribute('aria-current') === 'true',
+ link => link.getAttribute('aria-current') === 'location',
);
if (active == null) {
return;
@@ -465,7 +465,7 @@ export function Outline({
<li key={item.id} {...stylex.props(styles.item)} role="listitem">
<LinkComponent
href={`#${item.id}`}
- aria-current={isActive ? 'true' : undefined}
+ aria-current={isActive ? 'location' : undefined}
onClick={handleClick(item.id)}
onKeyDown={handleKeyDown(item.id)}
{...mergeProps(
diff --git a/packages/core/src/TopNav/TopNav.test.tsx b/packages/core/src/TopNav/TopNav.test.tsx
index 3b7d2337be..75fb34a076 100644
--- a/packages/core/src/TopNav/TopNav.test.tsx
+++ b/packages/core/src/TopNav/TopNav.test.tsx
@@ -420,12 +420,103 @@ describe('TopNavItem', () => {
it('applies aria-disabled when isDisabled', () => {
render(<TopNavItem label="Home" href="#" isDisabled />);
- expect(screen.getByRole('link')).toHaveAttribute('aria-disabled', 'true');
+ expect(screen.getByText('Home').closest('a')).toHaveAttribute(
+ 'aria-disabled',
+ 'true',
+ );
});
it('sets tabIndex to -1 when disabled', () => {
render(<TopNavItem label="Home" href="#" isDisabled />);
- expect(screen.getByRole('link')).toHaveAttribute('tabIndex', '-1');
+ expect(screen.getByText('Home').closest('a')).toHaveAttribute(
+ 'tabIndex',
+ '-1',
+ );
+ });
+
+ describe('disabled items do not navigate', () => {
+ it('drops href/target and suppresses clicks when disabled (default mode)', () => {
+ const handleClick = vi.fn();
+ render(
+ <TopNavItem
+ label="Home"
+ href="/home"
+ target="_blank"
+ onClick={handleClick}
+ isDisabled
+ />,
+ );
+ // An href-less anchor exposes no link role, so it is not announced
+ // with a live destination.
+ expect(screen.queryByRole('link')).not.toBeInTheDocument();
+ const item = screen.getByText('Home').closest('a') as HTMLAnchorElement;
+ expect(item).not.toHaveAttribute('href');
+ expect(item).not.toHaveAttribute('target');
+ expect(item).toHaveAttribute('aria-disabled', 'true');
+ expect(item).toHaveAttribute('tabIndex', '-1');
+
+ // fireEvent bypasses pointer-events: none, simulating programmatic/AT
+ // activation. It returns false when preventDefault was called, i.e.
+ // any default navigation behavior is cancelled.
+ const notCancelled = fireEvent.click(item);
+ expect(notCancelled).toBe(false);
+ expect(handleClick).not.toHaveBeenCalled();
+ });
+
+ it('drops href/target and suppresses clicks when disabled (drawer mode)', () => {
+ const handleClick = vi.fn();
+ render(
+ <TopNavRenderContext value="drawer">
+ <TopNavItem
+ label="Home"
+ href="/home"
+ target="_blank"
+ onClick={handleClick}
+ isDisabled
+ />
+ </TopNavRenderContext>,
+ );
+ expect(screen.queryByRole('link')).not.toBeInTheDocument();
+ const item = screen.getByText('Home').closest('a') as HTMLAnchorElement;
+ expect(item).not.toHaveAttribute('href');
+ expect(item).not.toHaveAttribute('target');
+ expect(item).toHaveAttribute('aria-disabled', 'true');
+ expect(item).toHaveAttribute('tabIndex', '-1');
+
+ // fireEvent bypasses pointer-events: none, simulating programmatic/AT
+ // activation. It returns false when preventDefault was called.
+ const notCancelled = fireEvent.click(item);
+ expect(notCancelled).toBe(false);
+ expect(handleClick).not.toHaveBeenCalled();
+ });
+
+ it('keeps href and click behavior for enabled items (default mode)', async () => {
+ const user = userEvent.setup();
+ const handleClick = vi.fn();
+ render(<TopNavItem label="Home" href="#" onClick={handleClick} />);
+ const link = screen.getByRole('link', {name: 'Home'});
+ expect(link).toHaveAttribute('href', '#');
+ expect(link).not.toHaveAttribute('aria-disabled');
+
+ await user.click(link);
+ expect(handleClick).toHaveBeenCalledTimes(1);
+ });
+
+ it('keeps href and click behavior for enabled items (drawer mode)', async () => {
+ const user = userEvent.setup();
+ const handleClick = vi.fn();
+ render(
+ <TopNavRenderContext value="drawer">
+ <TopNavItem label="Home" href="#" onClick={handleClick} />
+ </TopNavRenderContext>,
+ );
+ const link = screen.getByRole('link', {name: 'Home'});
+ expect(link).toHaveAttribute('href', '#');
+ expect(link).not.toHaveAttribute('aria-disabled');
+
+ await user.click(link);
+ expect(handleClick).toHaveBeenCalledTimes(1);
+ });
});
it('renders icon with label', () => {
diff --git a/packages/core/src/TopNav/TopNavItem.doc.mjs b/packages/core/src/TopNav/TopNavItem.doc.mjs
index 78399016bf..06c657e142 100644
--- a/packages/core/src/TopNav/TopNavItem.doc.mjs
+++ b/packages/core/src/TopNav/TopNavItem.doc.mjs
@@ -29,7 +29,7 @@ export const docs = {
{
name: 'isDisabled',
type: 'boolean',
- description: 'Whether the nav item is disabled. Sets aria-disabled and prevents interaction.',
+ description: 'Whether the nav item is disabled. Sets aria-disabled, drops href/target so the item cannot navigate, and prevents interaction.',
default: 'false',
},
{
@@ -91,7 +91,7 @@ export const docsZh = {
{
name: 'isDisabled',
type: 'boolean',
- description: '导航项是否被禁用。设置 aria-disabled 并阻止交互。',
+ description: '导航项是否被禁用。设置 aria-disabled,移除 href/target 使其无法导航,并阻止交互。',
default: 'false',
},
{
@@ -121,7 +121,7 @@ export const docsDense = {
label: 'Visible text or aria-label when isIconOnly is true.',
href: 'Navigation URL.',
isSelected: 'Sets aria-current="page"+highlighted styles.',
- isDisabled: 'Sets aria-disabled, prevents interaction.',
+ isDisabled: 'Sets aria-disabled, drops href/target (no navigation), prevents interaction.',
icon: 'Icon before label.',
children: 'Custom content instead of label text.',
as: 'Custom link component. Overrides LinkProvider default. Must accept href, className, style, children.',
diff --git a/packages/core/src/TopNav/TopNavItem.tsx b/packages/core/src/TopNav/TopNavItem.tsx
index 0bc3d28aae..a1e800caa4 100644
--- a/packages/core/src/TopNav/TopNavItem.tsx
+++ b/packages/core/src/TopNav/TopNavItem.tsx
@@ -131,6 +131,8 @@ export interface TopNavItemProps extends BaseProps<HTMLAnchorElement> {
isSelected?: boolean;
/**
* Whether the nav item is disabled.
+ * A disabled item renders as a plain anchor without an href (and without
+ * target), so it cannot navigate and is removed from the tab order.
* @default false
*/
isDisabled?: boolean;
@@ -157,6 +159,15 @@ export interface TopNavItemProps extends BaseProps<HTMLAnchorElement> {
size?: NavItemSize;
}
+/**
+ * Click handler for disabled items. The disabled anchor renders without an
+ * href, so there is no navigation to block in practice; preventDefault is a
+ * defensive guard against synthetic/programmatic clicks.
+ */
+function preventDefaultClick(event: React.MouseEvent<HTMLAnchorElement>): void {
+ event.preventDefault();
+}
+
/**
* A navigation item for use within TopNav startContent.
*
@@ -178,6 +189,9 @@ export interface TopNavItemProps extends BaseProps<HTMLAnchorElement> {
*/
export function TopNavItem({
as,
+ href,
+ target,
+ onClick,
label,
isSelected = false,
isDisabled = false,
@@ -195,22 +209,34 @@ export function TopNavItem({
const renderMode = useTopNavRenderMode();
const {closeMobileNav} = useAppShellMobile();
+ // A disabled item renders as a plain <a> with no href: an href-less anchor
+ // is not focusable and exposes no link affordance, so programmatic focus +
+ // Enter, AT activation commands, and middle-click cannot navigate or fire
+ // the consumer onClick. The router LinkComponent is deliberately skipped —
+ // a disabled item performs no navigation, and custom router links may
+ // require a live href. target is omitted with the href. (Mirrors the
+ // disabled paths of Link and SideNavItem.)
+ const Root = isDisabled ? 'a' : LinkComponent;
+
// =========================================================================
// Drawer mode — render as a SideNavItem-style vertical list element
// =========================================================================
if (renderMode === 'drawer') {
- const handleDrawerClick = (e: React.MouseEvent) => {
+ const handleDrawerClick = (e: React.MouseEvent<HTMLAnchorElement>) => {
if (isDisabled) {
+ preventDefaultClick(e);
return;
}
// Forward the original onClick if present
- (props as {onClick?: (e: React.MouseEvent) => void}).onClick?.(e);
+ onClick?.(e);
closeMobileNav();
};
return (
- <LinkComponent
+ <Root
ref={ref}
+ href={isDisabled ? undefined : href}
+ target={isDisabled ? undefined : target}
aria-label={isIconOnly ? label : undefined}
aria-current={isSelected ? 'page' : undefined}
aria-disabled={isDisabled || undefined}
@@ -235,7 +261,7 @@ export function TopNavItem({
onClick={handleDrawerClick}>
{icon}
{!isIconOnly && (children ?? label)}
- </LinkComponent>
+ </Root>
);
}
@@ -244,8 +270,11 @@ export function TopNavItem({
// =========================================================================
return (
- <LinkComponent
+ <Root
ref={ref}
+ href={isDisabled ? undefined : href}
+ target={isDisabled ? undefined : target}
+ onClick={isDisabled ? preventDefaultClick : onClick}
aria-label={isIconOnly ? label : undefined}
aria-current={isSelected ? 'page' : undefined}
aria-disabled={isDisabled || undefined}
@@ -267,7 +296,7 @@ export function TopNavItem({
{...props}>
{icon}
{!isIconOnly && (children ?? label)}
- </LinkComponent>
+ </Root>
);
}