improve the accessibility experience of the Anchor component when navigating to external pages.

sirineJ · sirineJ · commit 08d7182c7978 · 2025-03-13T17:00:21.000+01:00
diff --git a/.changeset/gentle-seahorses-press.md b/.changeset/gentle-seahorses-press.md
@@ -0,0 +1,5 @@
+---
+"@sumup-oss/circuit-ui": minor
+---
+
+Added two new props `isExternal` and  `externalLabel` to the Anchor component props to describe to visually impaired users that the link leads to an external page or opens in a new tab.
diff --git a/packages/circuit-ui/components/Anchor/Anchor.spec.tsx b/packages/circuit-ui/components/Anchor/Anchor.spec.tsx
@@ -107,6 +107,36 @@ describe('Anchor', () => {
     expect(onClick).toHaveBeenCalledTimes(1);
   });
 
+  it('should render as link with an description label when it renders an external link', () => {
+    render(
+      <Anchor
+        href="www.external.link.com"
+        {...baseProps}
+        isExternal
+        externalLabel="Opens in a new tab"
+      />,
+    );
+
+    expect(screen.getByRole('link')).toHaveAccessibleDescription(
+      'Opens in a new tab',
+    );
+  });
+
+  it('should render as button with an description label when it renders an external link', () => {
+    render(
+      <Anchor
+        onClick={vi.fn()}
+        {...baseProps}
+        isExternal
+        externalLabel="Opens in a new tab"
+      />,
+    );
+
+    expect(screen.getByRole('button')).toHaveAccessibleDescription(
+      'Opens in a new tab',
+    );
+  });
+
   it('should meet accessibility guidelines', async () => {
     const { container } = render(
       <Anchor {...baseProps} href="https://sumup.com" onClick={vi.fn} />,
diff --git a/packages/circuit-ui/components/Anchor/Anchor.tsx b/packages/circuit-ui/components/Anchor/Anchor.tsx
@@ -21,6 +21,7 @@ import {
   type ButtonHTMLAttributes,
   type ReactNode,
   type Ref,
+  useId,
 } from 'react';
 
 import type { ReturnType } from '../../types/return-type.js';
@@ -43,6 +44,14 @@ export interface BaseProps extends Omit<BodyProps, 'color'> {
    * The ref to the HTML DOM element, it can be a button an anchor or a span, typed as any for now because of complex js manipulation with styled components
    */
   ref?: Ref<any>;
+  /**
+   * Whether the link leads to an external page or opens in a new tab.
+   */
+  isExternal?: boolean;
+  /**
+   * Short label to describe that the link leads to an external page or opens in a new tab.
+   */
+  externalLabel?: string;
 }
 type LinkElProps = Omit<
   AnchorHTMLAttributes<HTMLAnchorElement>,
@@ -61,34 +70,67 @@ export type AnchorProps = BaseProps & LinkElProps & ButtonElProps;
  */
 export const Anchor = forwardRef(
   (
-    { className, ...props }: AnchorProps,
+    {
+      className,
+      isExternal,
+      externalLabel,
+      'aria-describedby': descriptionId,
+      children,
+      ...props
+    }: AnchorProps,
     ref?: BaseProps['ref'],
   ): ReturnType => {
     const components = useComponents();
     const Link = components.Link as AsPropType;
+    const externalLabelId = useId();
+    const descriptionIds = clsx(
+      externalLabel && externalLabelId,
+      descriptionId,
+    );
+    const isExternalLink = isExternal || props.target === '_blank';
 
     if (!props.href && !props.onClick) {
-      return <Body as="span" {...props} ref={ref} />;
+      return (
+        <Body as="span" {...props} ref={ref}>
+          {children}
+        </Body>
+      );
     }
 
     if (props.href) {
       return (
         <Body
           {...props}
+          aria-describedby={descriptionIds}
           className={clsx(classes.base, utilClasses.focusVisible, className)}
           as={Link}
           ref={ref}
-        />
+        >
+          {children}
+          {isExternalLink && externalLabel && (
+            <span id={externalLabelId} className={utilClasses.hideVisually}>
+              {externalLabel}
+            </span>
+          )}
+        </Body>
       );
     }
 
     return (
       <Body
         as="button"
         {...props}
+        aria-describedby={descriptionIds}
         className={clsx(classes.base, utilClasses.focusVisible, className)}
         ref={ref}
-      />
+      >
+        {children}
+        {isExternalLink && externalLabel && (
+          <span id={externalLabelId} className={utilClasses.hideVisually}>
+            {externalLabel}
+          </span>
+        )}
+      </Body>
     );
   },
 );
