From 72cc2a1e07bd7a3233a0c71c03ec2c8f06ae98f1 Mon Sep 17 00:00:00 2001
From: anuj-pal27 <anujpal27669@gmail.com>
Date: Sun, 18 Oct 2026 10:45:53 +0530
Subject: [PATCH] Add ariaLabelledBy prop to Dialog

Closes #2139
---
 .../components/dialog/code/DialogCodePage.tsx       | 13 +++++++++++++
 packages/lib/src/dialog/Dialog.test.tsx             |  9 +++++++++
 packages/lib/src/dialog/Dialog.tsx                  |  9 ++++++++-
 packages/lib/src/dialog/types.ts                    |  4 ++++
 4 files changed, 34 insertions(+), 1 deletion(-)

diff --git a/apps/website/screens/components/dialog/code/DialogCodePage.tsx b/apps/website/screens/components/dialog/code/DialogCodePage.tsx
index dad1b764b7..38584eb94e 100644
--- a/apps/website/screens/components/dialog/code/DialogCodePage.tsx
+++ b/apps/website/screens/components/dialog/code/DialogCodePage.tsx
@@ -22,6 +22,19 @@ const sections = [
           </tr>
         </thead>
         <tbody>
+          <tr>
+            <td>
+              <DxcFlex direction="column" gap="var(--spacing-gap-xs)" alignItems="baseline">
+                <StatusBadge status="new" />
+                ariaLabelledBy
+              </DxcFlex>
+            </td>
+            <td>
+              <TableCode>string</TableCode>
+            </td>
+            <td>Id of the element (usually the title of the dialog) that labels the dialog.</td>
+            <td>-</td>
+          </tr>
           <tr>
             <td>
               <DxcFlex direction="column" gap="var(--spacing-gap-xs)" alignItems="baseline">
diff --git a/packages/lib/src/dialog/Dialog.test.tsx b/packages/lib/src/dialog/Dialog.test.tsx
index 62fb3f7098..0309f5ab43 100644
--- a/packages/lib/src/dialog/Dialog.test.tsx
+++ b/packages/lib/src/dialog/Dialog.test.tsx
@@ -50,6 +50,15 @@ describe("Dialog component tests", () => {
     expect(getByRole("dialog")).toBeTruthy();
     expect(getByRole("dialog").getAttribute("aria-modal")).toBe("false");
   });
+  test("Dialog is labelled by the element referenced in ariaLabelledBy", () => {
+    const { getByRole } = render(
+      <DxcDialog ariaLabelledBy="dialog-title">
+        <h2 id="dialog-title">Delivery address</h2>
+      </DxcDialog>
+    );
+    expect(getByRole("dialog", { name: "Delivery address" })).toBeTruthy();
+    expect(getByRole("dialog").getAttribute("aria-label")).toBeNull();
+  });
   test("Calls correct function onCloseClick", () => {
     const onCloseClick = jest.fn();
     const { getByRole } = render(<DxcDialog onCloseClick={onCloseClick}>dialog-text</DxcDialog>);
diff --git a/packages/lib/src/dialog/Dialog.tsx b/packages/lib/src/dialog/Dialog.tsx
index adc9bdd339..ca7a8650cb 100644
--- a/packages/lib/src/dialog/Dialog.tsx
+++ b/packages/lib/src/dialog/Dialog.tsx
@@ -58,6 +58,7 @@ const CloseIconActionContainer = styled.div`
 `;
 
 const DxcDialog = ({
+  ariaLabelledBy,
   children,
   // Will have sense to be closable if onCloseClick is passed?
   closable = true,
@@ -97,7 +98,13 @@ const DxcDialog = ({
         createPortal(
           <DialogContainer>
             {overlay && <Overlay onClick={onBackgroundClick} />}
-            <Dialog aria-label="Dialog" aria-modal={overlay} closable={closable} role="dialog">
+            <Dialog
+              aria-label={ariaLabelledBy ? undefined : "Dialog"}
+              aria-labelledby={ariaLabelledBy}
+              aria-modal={overlay}
+              closable={closable}
+              role="dialog"
+            >
               {!disableFocusLock ? (
                 <FocusLock>
                   {children}
diff --git a/packages/lib/src/dialog/types.ts b/packages/lib/src/dialog/types.ts
index 558068c6e3..2fae84631f 100644
--- a/packages/lib/src/dialog/types.ts
+++ b/packages/lib/src/dialog/types.ts
@@ -1,6 +1,10 @@
 import { ReactNode } from "react";
 
 type Props = {
+  /**
+   * Id of the element (usually the title of the dialog) that labels the dialog.
+   */
+  ariaLabelledBy?: string;
   /**
    * If true, the close button will be visible.
    */