feat(dialog): add dialog header component - FE-7750 by DipperTheDan · Pull Request #8128 · Sage/carbon

DipperTheDan · 2026-08-12T08:34:09Z

Proposed behaviour

Refactor the HOC for heading variants.

Current behaviour

Currently we have a HOC for generating heading variants but this is overkill for what we need.

Checklist

QA

Tested in provided StackBlitz sandbox/Storybook
Add new Playwright test coverage if required
Carbon implementation matches Design System/designs
UI Tests GitHub check reviewed if required

Additional context

N/A

Testing instructions

There should be no visual or functional regressions with the heading variants of Dialog.
There should also be no regression associated with Dialog in general too.

ibutakova · 2026-08-13T10:33:34Z

@@ -264,7 +264,7 @@ const StyledDialogTitle = styled.div<StyledDialogTitleProps>`

  [data-element="dialog-title-help-wrapper"] {


Markup using dialog-title-help-wrapper is removed, so this selector looks dead, isn't it?

ibutakova · 2026-08-13T15:20:13Z

+        <Icon
+          type={iconType}
+          color={color}
+          fontSize="medium"


Check if fontSize is deprecated

Copilot

Warning

Copilot's review of this pull request may be incomplete because some of the changed files are excluded by your Copilot content exclusion settings. See Excluding content from Copilot for details.

Pull request overview

Replaces the Dialog heading HOC with an exported DialogHeader component and adds status-header accessibility support.

Changes:

Adds status variants, exports, stories, and documentation.
Adds ARIA ID coordination between Dialog and DialogHeader.
Updates tests and disables the deprecated help behavior.

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
`src/components/dialog/index.ts`	Exports the new header API.
`src/components/dialog/dialog.test.tsx`	Updates deprecated-help coverage.
`src/components/dialog/dialog.stories.tsx`	Adds status-header stories.
`src/components/dialog/dialog.pw.tsx`	Updates help and accessibility tests.
`src/components/dialog/dialog.mdx`	Documents status headers.
`src/components/dialog/dialog.component.tsx`	Re-exports header APIs.
`src/components/dialog/__internal__/__next__/index.ts`	Exports internal header APIs.
`src/components/dialog/__internal__/__next__/dialog.test.tsx`	Tests ARIA integration.
`src/components/dialog/__internal__/__next__/dialog.style.ts`	Adjusts header styling.
`src/components/dialog/__internal__/__next__/dialog.pw.tsx`	Adds no-subtitle accessibility coverage.
`src/components/dialog/__internal__/__next__/dialog.component.tsx`	Integrates `DialogHeader`.
`src/components/dialog/__internal__/__next__/dialog-test.stories.tsx`	Migrates HOC stories.
`src/components/dialog/__internal__/__next__/dialog-header/dialog-header.test.tsx`	Tests the new component.
`src/components/dialog/__internal__/__next__/dialog-header/dialog-header.component.tsx`	Implements `DialogHeader`.
`src/components/dialog/__internal__/__next__/components-test.pw.tsx`	Migrates Playwright fixtures.
`skills/carbon-react/components/alert.md`	Excluded documentation update.
`skills/carbon-react/components/dialog.md`	Excluded documentation update.

Files excluded by content exclusion policy (2)

skills/carbon-react/components/alert.md
skills/carbon-react/components/dialog.md

Suppressed comments (1)

src/components/dialog/internal/next/dialog.component.tsx:353

The generated title ID overrides an explicit aria-labelledby, even though DialogProps documents that prop for custom React-node titles and the previous HOC preserved it. Consumers can no longer supply a different accessible label when using DialogHeader; give the explicit prop precedence.

      "aria-labelledby":
        dialogHeaderTitleId ||
        (title && typeof title === "string" ? titleId : ariaLabelledBy),

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

      "aria-describedby":
-        subtitle && typeof subtitle === "string" ? subtitleId : ariaDescribedBy,
+        dialogHeaderSubtitleId ||
+        (subtitle && typeof subtitle === "string"
+          ? subtitleId
+          : ariaDescribedBy),


+  /**
+   * Adds Help tooltip to Header.
+   * @deprecated This prop no longer has any effect and will be removed in a future release.
+   */


+  open
+  title={
+    <DialogHeader
+      title="Dialog with status"


edleeks87 · 2026-08-20T14:17:34Z

-        );
-        passSubtitle = false;
+    // Always call hooks unconditionally at the top level
+    const generatedTitleId = useRef(createGuid()).current;


Suggested change

const generatedTitleId = useRef(createGuid()).current;

const generatedTitleId = useRef(context?.titleId || createGuid()).current;

non-blocking

edleeks87 · 2026-08-20T14:19:29Z

+
 /** Allowed status variants for the dialog heading icon. */
-export type DialogHeadingStatus =
+export type DialogHeading =


Suggested change

export type DialogHeading =

export type DialogHeadingStatus =

non-blocking, I think it was better when it was a bit more explicit

ibutakova · 2026-08-25T08:57:42Z

+    const isDialogHeader =
+      title &&
+      React.isValidElement(title) &&
+      title.type === DialogHeadingStatus;


suggestion(non-blocking): Since DialogHeader is exported from Dialog subpath and documented for consumer use, consumer can easily wrap it in memo or styled component, This means title.type === DialogHeadingStatus can fail. Can we do better or create a follow-up ticket?

I can make this change in this PR. It makes sense to do it now 👍🏻

edleeks87 · 2026-08-26T14:40:53Z

+    let dialogHeaderTitleId: string | undefined;
+    let dialogHeaderSubtitleId: string | undefined;
+
+    if (isDialogHeader && title && React.isValidElement(title)) {


suggestion: to avoid the casting we could do something like

const isValidDialogHeader = isDialogHeader && React.isValidElement<{ subtitle?: React.ReactNode }>(title);

edleeks87 · 2026-08-26T14:52:49Z

    const dialogTitle = () => {
-      const renderTitle = (
+      // Helper to render subtitle
+      const renderSubtitle = () => (


suggestion (non-blocking): we could add a short circuit here and then remove the boolean logic below but either is fine

if (!subtitle) return;

edleeks87 · 2026-08-26T14:54:44Z

+      const renderTitle = isDialogHeader ? (
+        <DialogHeadingStatusContext.Provider
+          value={{
+            titleId: dialogHeaderTitleId,


suggestion: if you go with the above change you can probably just pass titleId and subtitleId via the provider. I could be wrong on this one though as it may need a conditional check instead of greedily passing etc

edleeks87 · 2026-08-26T15:15:07Z

@@ -317,10 +367,14 @@ export const Dialog = forwardRef<DialogHandle, DialogProps>(

    const ariaProps = {


suggestion: these are a bit complicated to read with nested ternaries

const ariaProps = { "aria-describedby": (isValidDialogHeader && title.props.subtitle) || (subtitle && typeof subtitle === "string") ? subtitleId : ariaDescribedBy, "aria-label": ariaLabel, "aria-labelledby": (isValidDialogHeader || (title && typeof title === "string")) ? titleId : ariaLabelledBy, };

edleeks87 · 2026-08-26T15:23:48Z

    );

+    // Check if title is a DialogHeader component
+    const isDialogHeader = React.useMemo(() => {


suggestion: we could move this to some helper functions with typing to avoid the casting etc

// utils.ts const canHaveProperties = (value: unknown): value is object => value !== null && (typeof value === "object" || typeof value === "function"); const hasDialogHeadingStatusMarker = (value: unknown) => canHaveProperties(value) && "$$carbonDialogHeadingStatus" in value && value.$$carbonDialogHeadingStatus; export const isDialogHeadingStatusComponent = (componentType: unknown) => hasDialogHeadingStatusMarker(componentType) || (canHaveProperties(componentType) && "type" in componentType && hasDialogHeadingStatusMarker(componentType.type));

const isDialogHeader = React.useMemo(() => { if (!title || !React.isValidElement(title)) { return false; } // Check direct type match if (title.type === DialogHeadingStatus) { return true; } return isDialogHeadingStatusComponent(title.type); }, [title]);

edleeks87 · 2026-08-26T15:26:50Z

+  title: React.ReactNode;
+  subtitle?: React.ReactNode;
+  status: DialogHeadingStatus;
 }


suggestion: add the status interface here instead, and on line 55

const DialogHeadingStatus: DialogHeadingStatusComponent = forwardRef< ...

edleeks87 · 2026-08-26T15:27:26Z

+DialogHeadingStatus.displayName = "DialogHeadingStatus";

-  return Enhanced;
+// Static marker to identify this component even when wrapped in memo/styled-components


suggestion: if you go with the above then end of file can just be

DialogHeadingStatus.$$carbonDialogHeadingStatus = true; export default DialogHeadingStatus;

carbonci · 2026-09-10T13:13:40Z

🎉 This PR is included in version 161.25.0 🎉

The release is available on:

Your semantic-release bot 📦🚀

DipperTheDan self-assigned this Aug 12, 2026

DipperTheDan added Pending Review Pending QA No UX QA Required Squad Front End labels Aug 12, 2026

DipperTheDan force-pushed the dialog-heading-variants-spike branch from 79da4a3 to abc5558 Compare August 12, 2026 14:38

ibutakova self-requested a review August 13, 2026 10:51

ibutakova reviewed Aug 13, 2026

View reviewed changes

edleeks87 requested review from edleeks87 and a balanced review from Copilot August 20, 2026 09:06

Copilot started reviewing on behalf of edleeks87 August 20, 2026 09:07 View session

Copilot AI reviewed Aug 20, 2026

View reviewed changes

edleeks87 reviewed Aug 20, 2026

View reviewed changes

ibutakova previously approved these changes Aug 25, 2026

View reviewed changes

DipperTheDan dismissed ibutakova’s stale review via 0b157c4 August 26, 2026 12:11

edleeks87 reviewed Aug 26, 2026

View reviewed changes

edleeks87 previously approved these changes Sep 1, 2026

View reviewed changes

DipperTheDan dismissed edleeks87’s stale review via 2e939bd September 2, 2026 08:55

ibutakova previously approved these changes Sep 2, 2026

View reviewed changes

edleeks87 previously approved these changes Sep 3, 2026

View reviewed changes

DipperTheDan marked this pull request as ready for review September 3, 2026 10:17

DipperTheDan requested review from a team as code owners September 3, 2026 10:17

DipperTheDan added Passed Review and removed Pending Review labels Sep 3, 2026

DipperTheDan dismissed stale reviews from edleeks87 and ibutakova via 0c6530b September 4, 2026 12:59

paulrobinson88 approved these changes Sep 4, 2026

View reviewed changes

paulrobinson88 added Passed QA and removed Pending QA labels Sep 4, 2026

feat(dialog): add dialog header component

73628b1

DipperTheDan force-pushed the dialog-heading-variants-spike branch from 0c6530b to 73628b1 Compare September 10, 2026 12:42

ibutakova approved these changes Sep 10, 2026

View reviewed changes

edleeks87 marked this pull request as draft September 10, 2026 12:57

Merge branch 'master' into dialog-heading-variants-spike

ac8af60

edleeks87 approved these changes Sep 10, 2026

View reviewed changes

edleeks87 marked this pull request as ready for review September 10, 2026 13:00

DipperTheDan merged commit f73849f into master Sep 10, 2026
32 checks passed

DipperTheDan deleted the dialog-heading-variants-spike branch September 10, 2026 13:10

carbonci added the released label Sep 10, 2026

		@@ -264,7 +264,7 @@ const StyledDialogTitle = styled.div<StyledDialogTitleProps>`

		[data-element="dialog-title-help-wrapper"] {

	const generatedTitleId = useRef(createGuid()).current;
	const generatedTitleId = useRef(context?.titleId \|\| createGuid()).current;

	export type DialogHeading =
	export type DialogHeadingStatus =

		@@ -317,10 +367,14 @@ export const Dialog = forwardRef<DialogHandle, DialogProps>(

		const ariaProps = {

Uh oh!

Conversation

DipperTheDan commented Aug 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Proposed behaviour

Current behaviour

Checklist

QA

Additional context

Testing instructions

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

edleeks87 Aug 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

carbonci commented Sep 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

6 participants

DipperTheDan commented Aug 12, 2026 •

edited

Loading

edleeks87 Aug 26, 2026 •

edited

Loading