feat: Add ariaLabel property to icon component

Author: avinashbot

src/__tests__/snapshot-tests/__snapshots__/documenter.test.ts.snap

@@ -8890,12 +8890,19 @@ exports[`Documenter definition for icon matches the snapshot: icon 1`] = `
   "name": "Icon",
   "properties": [
     {
-      "description": "Specifies alternate text for a custom icon (using the \`url\` attribute). We recommend that you provide this for accessibility.
+      "deprecatedTag": "Use \`ariaLabel\` instead.",
+      "description": "Specifies alternate text for a custom icon (using the \`url\` attribute).
 This property is ignored if you use a predefined icon or if you set your custom icon using the \`svg\` slot.",
       "name": "alt",
       "optional": true,
       "type": "string",
     },
+    {
+      "description": "Specifies alternate text for the icon. We recommend that you provide this for accessibility.",
+      "name": "ariaLabel",
+      "optional": true,
+      "type": "string",
+    },
     {
       "deprecatedTag": "Custom CSS is not supported. For testing and other use cases, use [data attributes](https://developer.mozilla.org/en-US/docs/Learn/HTML/Howto/Use_data_attributes).",
       "description": "Adds the specified classes to the root element of the component.",

src/icon/__tests__/icon.test.tsx

@@ -85,6 +85,28 @@ describe('Icon Component', () => {
       expect(img).toHaveAttribute('alt', 'custom icon');
     });
 
+    test('should render a custom icon with alternate text when a url and ariaLabel are provided', () => {
+      const { container } = render(<Icon url={url} ariaLabel="custom icon" />);
+      const wrapper = createWrapper(container);
+      expect(wrapper.findIcon()!.getElement()).not.toHaveAttribute('aria-label');
+      expect(container.querySelector('img')).toHaveAttribute('alt', 'custom icon');
+    });
+
+    test('should prefer ariaLabel when alt is also provided', () => {
+      const { container } = render(<Icon url={url} alt="icon alt" ariaLabel="custom icon" />);
+      const wrapper = createWrapper(container);
+      expect(wrapper.findIcon()!.getElement()).not.toHaveAttribute('aria-label');
+      expect(container.querySelector('img')).toHaveAttribute('alt', 'custom icon');
+    });
+
+    test('should not set aria-hidden="true" for custom svg icons if an ariaLabel is provided', () => {
+      const { container } = render(<Icon svg={svg} ariaLabel="custom icon" />);
+      const wrapper = createWrapper(container);
+      expect(wrapper.findIcon()!.getElement()).not.toHaveAttribute('aria-hidden', 'true');
+      expect(wrapper.findIcon()!.getElement()).toHaveAttribute('role', 'img');
+      expect(wrapper.findIcon()!.getElement()).toHaveAttribute('aria-label', 'custom icon');
+    });
+
     test('should render a custom icon when both name and url are provided', () => {
       const { container } = render(<Icon url={url} name="calendar" />);
       const img = container.querySelector('img');
@@ -126,6 +148,20 @@ describe('Icon Component', () => {
     expect(container.firstElementChild).toBeEmptyDOMElement();
   });
 
+  test('sets role="img" and the label on the wrapper element when provided', () => {
+    const { container } = render(<Icon name="calendar" ariaLabel="Calendar" />);
+    const wrapper = createWrapper(container);
+    expect(wrapper.findIcon()!.getElement()).toHaveAttribute('role', 'img');
+    expect(wrapper.findIcon()!.getElement()).toHaveAttribute('aria-label', 'Calendar');
+  });
+
+  test('sets role="img" and the label on the wrapper element even when ariaLabel is an empty string', () => {
+    const { container } = render(<Icon name="calendar" ariaLabel="" />);
+    const wrapper = createWrapper(container);
+    expect(wrapper.findIcon()!.getElement()).toHaveAttribute('role', 'img');
+    expect(wrapper.findIcon()!.getElement()).toHaveAttribute('aria-label', '');
+  });
+
   describe('Prototype Pollution attack', () => {
     beforeEach(() => {
       (Object.prototype as any).attack = '<b>vulnerable</b>';

src/icon/interfaces.ts

@@ -9,6 +9,7 @@ export interface IconProps extends BaseComponentProps {
    * Specifies the icon to be displayed.
    */
   name?: IconProps.Name;
+
   /**
    * Specifies the size of the icon.
    *
@@ -32,12 +33,20 @@ export interface IconProps extends BaseComponentProps {
    * If you set both `url` and `svg`, `svg` will take precedence.
    */
   url?: string;
+
   /**
-   * Specifies alternate text for a custom icon (using the `url` attribute). We recommend that you provide this for accessibility.
+   * Specifies alternate text for a custom icon (using the `url` attribute).
    * This property is ignored if you use a predefined icon or if you set your custom icon using the `svg` slot.
+   *
+   * @deprecated Use `ariaLabel` instead.
    */
   alt?: string;
 
+  /**
+   * Specifies alternate text for the icon. We recommend that you provide this for accessibility.
+   */
+  ariaLabel?: string;
+
   /**
    * Specifies the SVG of a custom icon.
    *

src/icon/internal.tsx

@@ -44,6 +44,7 @@ const InternalIcon = ({
   variant = 'normal',
   url,
   alt,
+  ariaLabel,
   svg,
   badge,
   __internalRootRef = null,
@@ -82,6 +83,8 @@ const InternalIcon = ({
   });
 
   const mergedRef = useMergeRefs(iconRef, __internalRootRef);
+  const hasAriaLabel = typeof ariaLabel === 'string';
+  const labelAttributes = hasAriaLabel ? { role: 'img', 'aria-label': ariaLabel } : {};
 
   if (svg) {
     if (url) {
@@ -91,7 +94,7 @@ const InternalIcon = ({
       );
     }
     return (
-      <span {...baseProps} ref={mergedRef} aria-hidden="true" style={inlineStyles}>
+      <span {...baseProps} {...labelAttributes} ref={mergedRef} aria-hidden={!hasAriaLabel} style={inlineStyles}>
         {svg}
       </span>
     );
@@ -100,7 +103,7 @@ const InternalIcon = ({
   if (url) {
     return (
       <span {...baseProps} ref={mergedRef} style={inlineStyles}>
-        <img src={url} alt={alt} />
+        <img src={url} alt={ariaLabel ?? alt} />
       </span>
     );
   }
@@ -131,7 +134,7 @@ const InternalIcon = ({
   }
 
   return (
-    <span {...baseProps} ref={mergedRef} style={inlineStyles}>
+    <span {...baseProps} {...labelAttributes} ref={mergedRef} style={inlineStyles}>
       {validIcon ? iconMap(name) : undefined}
     </span>
   );