From adf7df846e4acc511380a10cfd3d7f51d51cba30 Mon Sep 17 00:00:00 2001
From: Gethin Webster <gethinw@amazon.de>
Date: Thu, 29 Oct 2026 09:59:49 +0000
Subject: [PATCH] feat: add headerSecondaryContent and hideHeaderText to
 ExpandableSection

---
 .../header-secondary-content.page.tsx         | 234 +++++++++++++++++
 .../__snapshots__/documenter.test.ts.snap     |  19 +-
 .../__tests__/analytics-metadata.test.tsx     |  18 ++
 src/container/internal.tsx                    |  12 +-
 .../__tests__/analytics-metadata.test.tsx     |  16 ++
 .../__tests__/expandable-section.test.tsx     | 237 ++++++++++++++++++
 .../expandable-section-container.tsx          |  10 +
 .../expandable-section-header.tsx             | 157 ++++++++----
 src/expandable-section/interfaces.ts          |  13 +
 src/expandable-section/internal.tsx           |  16 +-
 src/expandable-section/styles.scss            |  32 +++
 src/expandable-section/utils.ts               |   4 +
 src/header/__tests__/header.test.tsx          |  12 +
 src/header/interfaces.ts                      |   5 +-
 src/header/internal.tsx                       |   9 +
 src/header/styles.scss                        |  22 ++
 16 files changed, 765 insertions(+), 51 deletions(-)
 create mode 100644 pages/expandable-section/header-secondary-content.page.tsx

diff --git a/pages/expandable-section/header-secondary-content.page.tsx b/pages/expandable-section/header-secondary-content.page.tsx
new file mode 100644
index 00000000000..787c286181d
--- /dev/null
+++ b/pages/expandable-section/header-secondary-content.page.tsx
@@ -0,0 +1,234 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import React, { useState } from 'react';
+
+import Badge from '~components/badge';
+import Box from '~components/box';
+import Button from '~components/button';
+import ButtonGroup from '~components/button-group';
+import ExpandableSection from '~components/expandable-section';
+import Input from '~components/input';
+import Link from '~components/link';
+import Popover from '~components/popover';
+import Select, { SelectProps } from '~components/select';
+import SpaceBetween from '~components/space-between';
+
+import { SimplePage } from '../app/templates';
+
+const languageOptions: SelectProps.Options = [
+  { label: 'SQL', value: 'sql' },
+  { label: 'PPL', value: 'ppl' },
+  { label: 'Logstash', value: 'logstash' },
+];
+
+function StandardExample() {
+  return (
+    <ExpandableSection variant="container" defaultExpanded={true} headerText="Standard expandable section">
+      Content
+    </ExpandableSection>
+  );
+}
+
+function CreateQueryExample() {
+  const [expanded, setExpanded] = useState(true);
+  const [language, setLanguage] = useState<SelectProps.Option>(languageOptions[0]);
+  return (
+    <ExpandableSection
+      variant="container"
+      headerText="Create query"
+      expanded={expanded}
+      onChange={({ detail }) => setExpanded(detail.expanded)}
+      headerSecondaryContent={
+        <Select
+          selectedOption={language}
+          onChange={({ detail }) => setLanguage(detail.selectedOption)}
+          options={languageOptions}
+          ariaLabel="Query language"
+        />
+      }
+      headerActions={
+        expanded ? (
+          <SpaceBetween direction="horizontal" size="xs">
+            <ButtonGroup
+              ariaLabel="Query actions"
+              variant="icon"
+              items={[
+                { type: 'icon-button', id: 'copy', iconName: 'copy', text: 'Copy' },
+                { type: 'icon-button', id: 'remove', iconName: 'remove', text: 'Clear' },
+              ]}
+            />
+            <Button>Save</Button>
+            <Button variant="primary">Run</Button>
+          </SpaceBetween>
+        ) : (
+          <Button variant="primary">Run</Button>
+        )
+      }
+    >
+      <Box color="text-body-secondary">SELECT * FROM logs WHERE status = 500 ORDER BY timestamp DESC LIMIT 100</Box>
+    </ExpandableSection>
+  );
+}
+
+function DescriptionAsSecondaryContentExample() {
+  return (
+    <ExpandableSection
+      variant="container"
+      defaultExpanded={true}
+      headerText="Production database"
+      headerSecondaryContent={<Box variant="small">Last synced 3 minutes ago</Box>}
+      headerActions={<Button>Refresh</Button>}
+    >
+      <Box color="text-body-secondary">
+        Supporting text can live in the secondary content slot next to the header text, instead of the description slot
+        below it.
+      </Box>
+    </ExpandableSection>
+  );
+}
+
+function HiddenHeaderTextExample() {
+  const sectionName = 'Data source A';
+  const [language, setLanguage] = useState<SelectProps.Option>(languageOptions[0]);
+  return (
+    <ExpandableSection
+      variant="container"
+      defaultExpanded={true}
+      headerText={sectionName}
+      hideHeaderText={true}
+      headerSecondaryContent={
+        <SpaceBetween direction="horizontal" size="xs" alignItems="center">
+          <Badge color="severity-low">
+            <Box padding={{ vertical: 'xxs' }} color="inherit">
+              <Popover content="Edit name...">
+                <Box fontSize="heading-m" color="inherit">
+                  A
+                </Box>
+              </Popover>
+            </Box>
+          </Badge>
+          <Select
+            selectedOption={language}
+            onChange={({ detail }) => setLanguage(detail.selectedOption)}
+            options={languageOptions}
+            ariaLabel="Query language"
+          />
+        </SpaceBetween>
+      }
+    >
+      <Box color="text-body-secondary">Configuration for {sectionName}.</Box>
+    </ExpandableSection>
+  );
+}
+
+function HiddenHeaderTextSearchExample() {
+  const [value, setValue] = useState('');
+  return (
+    <ExpandableSection
+      variant="container"
+      defaultExpanded={true}
+      headerText="Search results"
+      hideHeaderText={true}
+      headerSecondaryContent={
+        <Input
+          type="search"
+          value={value}
+          onChange={({ detail }) => setValue(detail.value)}
+          placeholder="Search results"
+          ariaLabel="Search results"
+        />
+      }
+    >
+      <Box color="text-body-secondary">Results matching “{value || 'your query'}”.</Box>
+    </ExpandableSection>
+  );
+}
+
+function AllHeaderSlotsExample() {
+  const [language, setLanguage] = useState<SelectProps.Option>(languageOptions[0]);
+  return (
+    <ExpandableSection
+      variant="container"
+      defaultExpanded={true}
+      headerText="Queries"
+      headerCounter="(3)"
+      headerInfo={<Link variant="info">Info</Link>}
+      headerDescription="Saved queries for the production log group."
+      headerSecondaryContent={
+        <Select
+          selectedOption={language}
+          onChange={({ detail }) => setLanguage(detail.selectedOption)}
+          options={languageOptions}
+          ariaLabel="Query language"
+        />
+      }
+      headerActions={<Button variant="primary">Run</Button>}
+    >
+      <Box color="text-body-secondary">Counter, info link, description, secondary content and actions together.</Box>
+    </ExpandableSection>
+  );
+}
+
+function LongContentExample() {
+  const [language, setLanguage] = useState<SelectProps.Option>(languageOptions[0]);
+  return (
+    <ExpandableSection
+      variant="container"
+      defaultExpanded={true}
+      headerText="Create query for the aggregated multi-region production log analytics dataset"
+      headerSecondaryContent={
+        <Select
+          selectedOption={language}
+          onChange={({ detail }) => setLanguage(detail.selectedOption)}
+          options={languageOptions}
+          ariaLabel="Query language"
+        />
+      }
+      headerActions={
+        <SpaceBetween direction="horizontal" size="xs">
+          <Button>Save</Button>
+          <Button variant="primary">Run</Button>
+        </SpaceBetween>
+      }
+    >
+      <Box color="text-body-secondary">Stress case: long header text next to an interactive control and actions.</Box>
+    </ExpandableSection>
+  );
+}
+
+export default function ExpandableSectionHeaderSecondaryContentPage() {
+  return (
+    <SimplePage title="Expandable section — header secondary content" screenshotArea={{}}>
+      <SpaceBetween size="l">
+        <div>
+          <h2>Standard</h2>
+          <StandardExample />
+        </div>
+        <div>
+          <h2>Interactive control alongside visible header text</h2>
+          <CreateQueryExample />
+        </div>
+        <div>
+          <h2>Description-style text as secondary content</h2>
+          <DescriptionAsSecondaryContentExample />
+        </div>
+        <div>
+          <h2>Interactive control with hidden header text</h2>
+          <HiddenHeaderTextExample />
+        </div>
+        <div>
+          <h2>Search input with hidden header text</h2>
+          <HiddenHeaderTextSearchExample />
+        </div>
+        <div>
+          <h2>Counter, info link and description with secondary content</h2>
+          <AllHeaderSlotsExample />
+        </div>
+        <div>
+          <h2>Long header text with control and actions</h2>
+          <LongContentExample />
+        </div>
+      </SpaceBetween>
+    </SimplePage>
+  );
+}
diff --git a/src/__tests__/snapshot-tests/__snapshots__/documenter.test.ts.snap b/src/__tests__/snapshot-tests/__snapshots__/documenter.test.ts.snap
index faa0a22efec..6cc040bf18f 100644
--- a/src/__tests__/snapshot-tests/__snapshots__/documenter.test.ts.snap
+++ b/src/__tests__/snapshot-tests/__snapshots__/documenter.test.ts.snap
@@ -14042,6 +14042,14 @@ slot (not with the deprecated \`header\`), and not with the navigation variant."
       "optional": true,
       "type": "string",
     },
+    {
+      "description": "Visually hides the header text while keeping it available to assistive technology.
+Use with \`headerSecondaryContent\` to present a purely interactive header control.
+Use with the default or container variant.",
+      "name": "hideHeaderText",
+      "optional": true,
+      "type": "boolean",
+    },
     {
       "deprecatedTag": "The usage of the \`id\` attribute is reserved for internal use cases. For testing and other use cases,
 use [data attributes](https://developer.mozilla.org/en-US/docs/Learn/HTML/Howto/Use_data_attributes). If you must
@@ -14100,6 +14108,12 @@ use the \`id\` attribute, consider setting it on a parent element instead.",
       "isDefault": false,
       "name": "headerInfo",
     },
+    {
+      "description": "Secondary content displayed next to the header text, such as an interactive control or supporting text.
+Use with the default or container variant.",
+      "isDefault": false,
+      "name": "headerSecondaryContent",
+    },
     {
       "description": "The heading text. Use plain text. When using the container variant, you can use additional header props like \`headerDescription\` and \`headerCounter\` to display other elements in the header.",
       "isDefault": false,
@@ -16005,16 +16019,19 @@ exports[`Components definition for header matches the snapshot: header 1`] = `
     },
     {
       "description": "Overrides the default [HTML heading tag](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements)
-provided by the variant. Using this property does not change the visual appearance of the component.",
+provided by the variant. Set to \`div\` to render the title without heading semantics. Using this property does not
+change the visual appearance of the component.",
       "inlineType": {
         "name": "HeaderProps.HeadingTag",
         "type": "union",
         "values": [
+          "div",
           "h1",
           "h2",
           "h3",
           "h4",
           "h5",
+          "h6",
         ],
       },
       "name": "headingTagOverride",
diff --git a/src/container/__tests__/analytics-metadata.test.tsx b/src/container/__tests__/analytics-metadata.test.tsx
index 33186fb9e1a..9497c095a7a 100644
--- a/src/container/__tests__/analytics-metadata.test.tsx
+++ b/src/container/__tests__/analytics-metadata.test.tsx
@@ -73,6 +73,24 @@ describe('Container renders correct analytics metadata', () => {
       expect(getGeneratedAnalyticsMetadata(element)).toEqual(getMetadataContexts(label));
     });
   });
+
+  describe.each<HeaderProps.HeadingTag>(['h4', 'h6', 'div'])(
+    'With a Header component and headingTagOverride=%s',
+    tag => {
+      test('resolves the label from the header text', () => {
+        const label = 'Container header';
+        const element = renderContainer({
+          header: (
+            <Header counter="100" info="Info" headingTagOverride={tag}>
+              {label}
+            </Header>
+          ),
+        });
+        validateComponentNameAndLabels(element, labels);
+        expect(getGeneratedAnalyticsMetadata(element)).toEqual(getMetadataContexts(label));
+      });
+    }
+  );
 });
 
 test('Internal Container does not render "component" metadata', () => {
diff --git a/src/container/internal.tsx b/src/container/internal.tsx
index c7ac8f4bf01..c65cb05b13a 100644
--- a/src/container/internal.tsx
+++ b/src/container/internal.tsx
@@ -21,6 +21,7 @@ import { ContainerProps } from './interfaces';
 import { getContentStyles, getFooterStyles, getHeaderStyles, getMediaStyles, getRootStyles } from './style';
 import { StickyHeaderContext, useStickyHeader } from './use-sticky-header';
 
+import headerAnalyticsSelectors from '../header/analytics-metadata/styles.css.js';
 import analyticsSelectors from './analytics-metadata/styles.css.js';
 import styles from './styles.css.js';
 import testStyles from './test-classes/styles.css.js';
@@ -53,6 +54,12 @@ export interface InternalContainerProps extends Omit<ContainerProps, 'variant'>,
   __contentKey?: string;
 
   styleClassNames?: StyleClassNames;
+
+  /**
+   * Native attributes spread onto the container root, for ARIA that `getBaseProps` does not forward
+   * (it forwards only id/className/data-*).
+   */
+  __nativeAttributes?: React.HTMLAttributes<HTMLDivElement>;
 }
 
 // Style API v2
@@ -103,6 +110,7 @@ const InternalContainer = React.forwardRef(function InternalContainer(
     __subStepRef,
     __contentKey,
     styleClassNames,
+    __nativeAttributes,
     ...restProps
   }: InternalContainerProps,
   ref: React.Ref<ContainerProps.Ref>
@@ -167,6 +175,7 @@ const InternalContainer = React.forwardRef(function InternalContainer(
     <div
       {...baseProps}
       {...__funnelSubStepProps}
+      {...__nativeAttributes}
       className={clsx(
         styleClassNames?.root,
         baseProps.className,
@@ -182,7 +191,8 @@ const InternalContainer = React.forwardRef(function InternalContainer(
       ref={mergedRef}
       onBlur={onRootBlur}
       {...getAnalyticsLabelAttribute(
-        `.${analyticsSelectors.header} h1, .${analyticsSelectors.header} h2, .${analyticsSelectors.header} h3`
+        // heading-text covers Header titles rendered outside h1-h3 via headingTagOverride.
+        `.${analyticsSelectors.header} :is(h1, h2, h3, .${headerAnalyticsSelectors['heading-text']})`
       )}
       style={getRootStyles(style)}
     >
diff --git a/src/expandable-section/__tests__/analytics-metadata.test.tsx b/src/expandable-section/__tests__/analytics-metadata.test.tsx
index de364ab2a77..9326acf216f 100644
--- a/src/expandable-section/__tests__/analytics-metadata.test.tsx
+++ b/src/expandable-section/__tests__/analytics-metadata.test.tsx
@@ -81,6 +81,22 @@ describe('Expandable section renders correct analytics metadata', () => {
       );
     });
   });
+  test.each(['container', 'stacked'])(
+    '%s variant resolves the label from header text when hideHeaderText hides the title',
+    variant => {
+      const wrapper = renderExpandableSection({
+        headerText: 'header',
+        children: 'content',
+        variant: variant as ExpandableSectionProps['variant'],
+        hideHeaderText: true,
+      });
+      // The title renders as a div (not h1/h2/h3) when hidden, so the label must resolve from the
+      // header-text marker class instead of the heading element.
+      expect(getGeneratedAnalyticsMetadata(wrapper.findExpandButton()!.getElement())).toEqual(
+        getExpandMetadata('header', variant, false)
+      );
+    }
+  );
   test.each(['container', 'stacked'])('%s variant with additional properties', variant => {
     const wrapper = renderExpandableSection({
       headerText: 'header',
diff --git a/src/expandable-section/__tests__/expandable-section.test.tsx b/src/expandable-section/__tests__/expandable-section.test.tsx
index 38b4ada0e00..a9e719b5d5b 100644
--- a/src/expandable-section/__tests__/expandable-section.test.tsx
+++ b/src/expandable-section/__tests__/expandable-section.test.tsx
@@ -35,6 +35,7 @@ function renderExpandableSection(props: ExpandableSectionProps = {}): Expandable
 
 const containerizedVariants: ExpandableSectionProps.Variant[] = ['container', 'stacked'];
 const variantsWithActions: ExpandableSectionProps.Variant[] = ['container', 'stacked', 'default', 'inline'];
+const variantsWithSecondaryContent: ExpandableSectionProps.Variant[] = ['container', 'stacked', 'default'];
 
 describe('Expandable Section', () => {
   const variantsWithDescription: ExpandableSectionProps.Variant[] = [
@@ -125,6 +126,85 @@ describe('Expandable Section', () => {
         });
       }
     });
+    describe('populates header secondary content slot correctly', () => {
+      for (const variant of variantsWithSecondaryContent) {
+        test(`${variant} variant renders the control outside the trigger`, () => {
+          const wrapper = renderExpandableSection({
+            headerText: 'Test Header',
+            variant,
+            headerSecondaryContent: <Button data-testid="interactive">Interactive</Button>,
+          });
+          const interactive = wrapper.findHeader().find('[data-testid="interactive"]');
+          expect(interactive).toBeTruthy();
+          expect(interactive!.getElement()).toHaveTextContent('Interactive');
+          // The control must not be nested inside the trigger (so activating it is not a trigger click)
+          // nor inside a heading element.
+          expect(wrapper.findExpandButton().getElement().contains(interactive!.getElement())).toBe(false);
+          expect(interactive!.getElement().closest('h1,h2,h3,h4,h5,h6')).toBeNull();
+        });
+
+        test(`${variant} variant: activating the control does not expand the section`, () => {
+          const wrapper = renderExpandableSection({
+            headerText: 'Test Header',
+            variant,
+            headerSecondaryContent: <Button data-testid="interactive">Interactive</Button>,
+          });
+          expect(wrapper.findExpandButton().getElement()).toHaveAttribute('aria-expanded', 'false');
+          wrapper.findHeader().find<HTMLButtonElement>('[data-testid="interactive"]')!.click();
+          expect(wrapper.findExpandButton().getElement()).toHaveAttribute('aria-expanded', 'false');
+        });
+      }
+    });
+    describe('headerSecondaryContent opts the collapsed header out of the no-actions layout', () => {
+      for (const variant of variantsWithSecondaryContent) {
+        test(`${variant} variant`, () => {
+          const withoutSecondary = renderExpandableSection({ headerText: 'Test Header', variant });
+          expect(withoutSecondary.findHeader().getElement()).toHaveClass(
+            styles['wrapper-not-expanded-without-actions']
+          );
+
+          const withSecondary = renderExpandableSection({
+            headerText: 'Test Header',
+            variant,
+            headerSecondaryContent: <Button>Interactive</Button>,
+          });
+          expect(withSecondary.findHeader().getElement()).not.toHaveClass(
+            styles['wrapper-not-expanded-without-actions']
+          );
+        });
+      }
+    });
+    describe('hideHeaderText keeps the header text accessible while visually hiding it', () => {
+      for (const variant of variantsWithSecondaryContent) {
+        test(`${variant} variant`, () => {
+          const wrapper = renderExpandableSection({
+            headerText: 'Test Header',
+            variant,
+            hideHeaderText: true,
+          });
+          // Text remains in the DOM (available to assistive technology) but visually hidden.
+          expect(wrapper.findHeaderText()!.getElement()).toHaveTextContent('Test Header');
+          expect(wrapper.findHeaderText()!.getElement()).toHaveClass(styles['header-text-hidden']);
+        });
+      }
+    });
+    describe('headerSecondaryContent and hideHeaderText take no effect on unsupported variants', () => {
+      for (const variant of ['footer', 'navigation', 'inline'] as ExpandableSectionProps.Variant[]) {
+        test(`${variant} variant keeps the header text visible and ignores secondary content`, () => {
+          const wrapper = renderExpandableSection({
+            headerText: 'Test Header',
+            variant,
+            hideHeaderText: true,
+            headerSecondaryContent: <Button data-testid="interactive">Interactive</Button>,
+          });
+          const headerText = wrapper.findHeaderText();
+          if (headerText) {
+            expect(headerText.getElement()).not.toHaveClass(styles['header-text-hidden']);
+          }
+          expect(wrapper.findHeader().find('[data-testid="interactive"]')).toBeNull();
+        });
+      }
+    });
     test.each<ExpandableSectionProps.Variant>(['default', 'footer', 'container', 'navigation', 'stacked', 'inline'])(
       'populates content slot correctly for "%s" variant',
       variant => {
@@ -338,6 +418,19 @@ describe('Expandable Section', () => {
       );
     });
 
+    test('logs warning when hideHeaderText is set without headerText', () => {
+      render(<ExpandableSection variant="container" hideHeaderText={true} />);
+      expect(warnOnce).toHaveBeenCalledWith(
+        componentName,
+        'The `hideHeaderText` prop requires `headerText` to be set.'
+      );
+    });
+
+    test('does not warn when hideHeaderText is set with headerText', () => {
+      render(<ExpandableSection variant="container" headerText="Data source A" hideHeaderText={true} />);
+      expect(warnOnce).not.toHaveBeenCalled();
+    });
+
     describe('logs warning for non supported configurations', () => {
       describe('headerDescription', () => {
         for (const variant of variantsWithoutDescription) {
@@ -372,6 +465,16 @@ describe('Expandable Section', () => {
                 testWarnings({ variant, headerActions: <Button>Action</Button> });
               });
             }
+            if (!variantsWithSecondaryContent.includes(variant)) {
+              test('headerSecondaryContent', () => {
+                testWarnings({ variant, headerSecondaryContent: <Button>Interactive</Button> });
+              });
+              test('hideHeaderText', () => {
+                render(<ExpandableSection variant={variant} headerText="Data source A" hideHeaderText={true} />);
+                expect(warnOnce).toHaveBeenCalledTimes(1);
+                expect(warnOnce).toHaveBeenCalledWith(componentName, expect.stringMatching(/only supported for the/));
+              });
+            }
           });
         }
       });
@@ -949,3 +1052,137 @@ describe('__expandIconPosition', () => {
     });
   });
 });
+
+describe('hideHeaderText a11y', () => {
+  describe('drops the heading element and labels the trigger with the header text', () => {
+    for (const variant of variantsWithSecondaryContent) {
+      test(`${variant} variant`, () => {
+        const wrapper = renderExpandableSection({ variant, headerText: 'Data source A', hideHeaderText: true });
+        expect(wrapper.findHeader().findAll('h1,h2,h3,h4,h5,h6').length).toBe(0);
+        expect(wrapper.findExpandButton().getElement()).toHaveAccessibleName('Data source A');
+      });
+    }
+  });
+
+  describe('exposes the section as a labelled region', () => {
+    for (const variant of variantsWithSecondaryContent) {
+      test(`${variant} variant is a region labelled by the header text`, () => {
+        const wrapper = renderExpandableSection({ variant, headerText: 'Data source A', hideHeaderText: true });
+        expect(wrapper.getElement()).toHaveAttribute('role', 'region');
+        expect(wrapper.getElement()).toHaveAccessibleName('Data source A');
+      });
+
+      test(`${variant} variant region prefers headerAriaLabel over the header text`, () => {
+        const wrapper = renderExpandableSection({
+          variant,
+          headerText: 'Data source A',
+          headerAriaLabel: 'Pick a data source',
+          hideHeaderText: true,
+        });
+        expect(wrapper.getElement()).toHaveAttribute('role', 'region');
+        expect(wrapper.getElement()).toHaveAttribute('aria-label', 'Pick a data source');
+      });
+    }
+  });
+
+  test('does not add a region role when the header text is visible', () => {
+    const wrapper = renderExpandableSection({ variant: 'container', headerText: 'Data source A' });
+    expect(wrapper.getElement()).not.toHaveAttribute('role', 'region');
+  });
+
+  test('does not add a region role for a variant that does not support hideHeaderText', () => {
+    const wrapper = renderExpandableSection({
+      variant: 'navigation',
+      headerText: 'Data source A',
+      hideHeaderText: true,
+    });
+    expect(wrapper.getElement()).not.toHaveAttribute('role', 'region');
+  });
+
+  test('validates a11y for a container with hidden header text and a control', async () => {
+    const { container } = render(
+      <ExpandableSection
+        variant="container"
+        headerText="Data source A"
+        hideHeaderText={true}
+        headerSecondaryContent={<Button>Refresh</Button>}
+      />
+    );
+    await expect(container).toValidateA11y();
+  });
+});
+
+describe('headerSecondaryContent describes the trigger', () => {
+  for (const variant of variantsWithSecondaryContent) {
+    test(`${variant} variant, visible header text`, () => {
+      const wrapper = renderExpandableSection({
+        variant,
+        headerText: 'Production database',
+        headerSecondaryContent: <span>Last synced 3 minutes ago</span>,
+      });
+      expect(wrapper.findExpandButton().getElement()).toHaveAccessibleDescription('Last synced 3 minutes ago');
+    });
+
+    test(`${variant} variant, hidden header text`, () => {
+      const wrapper = renderExpandableSection({
+        variant,
+        headerText: 'Data source A',
+        hideHeaderText: true,
+        headerSecondaryContent: <span>Choose a source</span>,
+      });
+      expect(wrapper.findExpandButton().getElement()).toHaveAccessibleDescription('Choose a source');
+    });
+  }
+
+  test('does not set aria-describedby when no secondary content is provided', () => {
+    const wrapper = renderExpandableSection({ variant: 'container', headerText: 'Production database' });
+    expect(wrapper.findExpandButton().getElement()).not.toHaveAttribute('aria-describedby');
+  });
+});
+
+describe('header secondary content with the expand icon at the end', () => {
+  function renderWithEndIcon(props: ExpandableSectionProps) {
+    const { container } = render(<InternalExpandableSection __expandIconPosition="end" {...props} />);
+    return createWrapper(container).findExpandableSection()!;
+  }
+
+  test('default variant renders the caret as a standalone button after the secondary control', () => {
+    const wrapper = renderWithEndIcon({
+      variant: 'default',
+      headerText: 'Create query',
+      headerSecondaryContent: <button type="button">Language</button>,
+    });
+    const header = wrapper.findHeader()!.getElement();
+    // With the caret at the end and secondary content present, the caret is a standalone <button>
+    // (its own expansion control) rather than an inline icon within the text-side trigger.
+    const caret = header.querySelector('button[aria-expanded]')!;
+    const secondaryControl = wrapper.findHeader()!.find('button:not([aria-expanded])')!.getElement();
+    expect(caret).toBeTruthy();
+    expect(caret.compareDocumentPosition(secondaryControl) & Node.DOCUMENT_POSITION_PRECEDING).toBeTruthy();
+  });
+
+  test('the standalone end caret carries the secondary content as its accessible description', () => {
+    const wrapper = renderWithEndIcon({
+      variant: 'container',
+      headerText: 'Data source A',
+      headerSecondaryContent: <span>Choose a source</span>,
+    });
+    expect(wrapper.findExpandButton().getElement()).toHaveAccessibleDescription('Choose a source');
+  });
+
+  test('hiding the header text leaves the standalone caret as the sole expansion tab stop', () => {
+    const wrapper = renderWithEndIcon({
+      variant: 'container',
+      headerText: 'Data source A',
+      hideHeaderText: true,
+      headerSecondaryContent: <button type="button">Language</button>,
+    });
+    const expansionButtons = wrapper
+      .findHeader()!
+      .findAll('[aria-expanded]')
+      .map(w => w.getElement());
+    // Only the standalone caret expands; the hidden text is not wrapped in a second focusable button.
+    expect(expansionButtons).toHaveLength(1);
+    expect(expansionButtons[0]).toBe(wrapper.findExpandButton().getElement());
+  });
+});
diff --git a/src/expandable-section/expandable-section-container.tsx b/src/expandable-section/expandable-section-container.tsx
index c0237133cf6..45567e636de 100644
--- a/src/expandable-section/expandable-section-container.tsx
+++ b/src/expandable-section/expandable-section-container.tsx
@@ -22,6 +22,9 @@ interface ExpandableSectionContainerProps extends InternalBaseComponentProps {
   children?: React.ReactNode;
   variant: InternalVariant;
   expanded: boolean | undefined;
+  role?: string;
+  ariaLabel?: string;
+  ariaLabelledby?: string;
   __injectAnalyticsComponentMetadata?: boolean;
 }
 
@@ -31,6 +34,9 @@ export const ExpandableSectionContainer = ({
   header,
   variant,
   expanded,
+  role,
+  ariaLabel,
+  ariaLabelledby,
   __internalRootRef,
   __injectAnalyticsComponentMetadata,
   ...rest
@@ -46,6 +52,8 @@ export const ExpandableSectionContainer = ({
     ? getAnalyticsMetadataAttribute({ component: analyticsComponentMetadata })
     : {};
 
+  const ariaProps = { role, ['aria-label']: ariaLabel, ['aria-labelledby']: ariaLabelledby };
+
   if (variant === 'container' || variant === 'stacked') {
     return (
       <AnalyticsFunnelSubStep
@@ -61,6 +69,7 @@ export const ExpandableSectionContainer = ({
           disableHeaderPaddings={true}
           __hiddenContent={!expanded}
           __internalRootRef={__internalRootRef}
+          __nativeAttributes={ariaProps}
           {...metadataAttribute}
         >
           {children}
@@ -73,6 +82,7 @@ export const ExpandableSectionContainer = ({
     <div
       className={className}
       {...rest}
+      {...ariaProps}
       ref={__internalRootRef}
       {...metadataAttribute}
       {...getAnalyticsLabelAttribute(`.${analyticsSelectors['header-label']}`)}
diff --git a/src/expandable-section/expandable-section-header.tsx b/src/expandable-section/expandable-section-header.tsx
index 03e0ae814f1..5b406c32d0b 100644
--- a/src/expandable-section/expandable-section-header.tsx
+++ b/src/expandable-section/expandable-section-header.tsx
@@ -20,6 +20,7 @@ import {
   variantRequiresActionsDivider,
   variantSupportsActions,
   variantSupportsDescription,
+  variantSupportsHeaderSecondaryContent,
   variantSupportsInfoLink,
 } from './utils';
 
@@ -32,6 +33,7 @@ interface ExpandIconButtonProps {
   icon: JSX.Element;
   ariaLabel?: string;
   ariaLabelledBy?: string;
+  ariaDescribedBy?: string;
   ariaControls: string;
   expanded: boolean;
   onClick: MouseEventHandler;
@@ -49,6 +51,7 @@ const ExpandIconButton = ({
   icon,
   ariaLabel,
   ariaLabelledBy,
+  ariaDescribedBy,
   ariaControls,
   expanded,
   onClick,
@@ -68,6 +71,7 @@ const ExpandIconButton = ({
       type="button"
       aria-label={ariaLabel}
       aria-labelledby={ariaLabelledBy}
+      aria-describedby={ariaDescribedBy}
       aria-controls={ariaControls}
       aria-expanded={expanded}
       data-awsui-motion-trigger="hover"
@@ -115,6 +119,9 @@ interface ExpandableHeaderTextWrapperProps extends ExpandableDefaultHeaderProps
   headerInfo?: ReactNode;
   headerActions?: ReactNode;
   headerEndInfo?: ReactNode;
+  headerSecondaryContent?: ReactNode;
+  secondaryContentId?: string;
+  hideHeaderText?: boolean;
   headingTagOverride?: ExpandableSectionProps.HeadingTag;
 }
 
@@ -125,6 +132,9 @@ interface ExpandableSectionHeaderProps extends Omit<ExpandableDefaultHeaderProps
   headerCounter?: string;
   headerInfo?: ReactNode;
   headerActions?: ReactNode;
+  headerSecondaryContent?: ReactNode;
+  secondaryContentId?: string;
+  hideHeaderText?: boolean;
   headingTagOverride?: ExpandableSectionProps.HeadingTag;
   ariaLabelledBy?: string;
   hideExpandIcon?: boolean;
@@ -246,6 +256,9 @@ const ExpandableHeaderTextWrapper = ({
   headerInfo,
   headerActions,
   headerEndInfo,
+  headerSecondaryContent,
+  secondaryContentId,
+  hideHeaderText,
   variant,
   headingTagOverride,
   onKeyUp,
@@ -253,9 +266,14 @@ const ExpandableHeaderTextWrapper = ({
   expandIconPosition,
 }: ExpandableHeaderTextWrapperProps) => {
   const isContainer = variant === 'container';
-  const HeadingTag = headingTagOverride || 'div';
   const supportsInteractiveElements = variantSupportsActions(variant);
-  const restrictClickableArea = (supportsInteractiveElements && (!!headerInfo || !!headerActions)) || !!headerEndInfo;
+  const supportsSecondaryContent = variantSupportsHeaderSecondaryContent(variant);
+  const hideText = supportsSecondaryContent && hideHeaderText;
+  const HeadingTag = hideText ? 'div' : headingTagOverride || 'div';
+  const secondaryContent = supportsSecondaryContent && headerSecondaryContent;
+  const describedById = secondaryContent ? secondaryContentId : undefined;
+  const restrictClickableArea =
+    (supportsInteractiveElements && (!!headerInfo || !!headerActions || !!secondaryContent)) || !!headerEndInfo;
   const actions = supportsInteractiveElements && headerActions;
   const endInfo = !isContainer && headerEndInfo;
   const description = variantSupportsDescription(variant) && headerDescription && (
@@ -263,12 +281,13 @@ const ExpandableHeaderTextWrapper = ({
       {headerDescription}
     </span>
   );
+  const ariaDescribedBy = clsx(description && descriptionId, describedById) || undefined;
   const listeners = { onClick, onKeyDown, onKeyUp };
   const iconAtEnd = expandIconPosition === 'end';
   // For the variants that allow actions, when end placement is active, the icon is rendered outside the
   // InternalHeader so it appears at the inline-end of the wrapper, past any header actions.
   // Other variants render the icon at the end of the headerButton itself.
-  const renderIconOutsideHeader = iconAtEnd && (isContainer || !!actions || !!endInfo);
+  const renderIconOutsideHeader = iconAtEnd && (isContainer || !!actions || !!endInfo || !!secondaryContent);
 
   // If interactive elements are present, constrain the clickable area to only the icon and the header text
   // to prevent nesting interactive elements.
@@ -294,6 +313,7 @@ const ExpandableHeaderTextWrapper = ({
       icon={icon}
       ariaLabel={ariaLabel}
       ariaLabelledBy={!ariaLabel ? id : undefined}
+      ariaDescribedBy={ariaDescribedBy}
       ariaControls={ariaControls}
       expanded={expanded}
       onClick={onClick}
@@ -319,44 +339,54 @@ const ExpandableHeaderTextWrapper = ({
   const outsideIcon = renderIconOutsideHeader ? expandButton : null;
 
   const textElement = (
-    <span id={id} className={clsx(styles['header-text'], analyticsSelectors['header-label'])}>
-      {children}
-    </span>
-  );
-  const headerButton = (
     <span
+      id={id}
       className={clsx(
-        styles['expand-button'],
-        isContainer ? styles['header-container-button'] : styles['header-button'],
-        iconAtEnd && styles['header-button-icon-end'],
-        headerButtonListeners && styles['click-target']
+        styles['header-text'],
+        hideText && styles['header-text-hidden'],
+        analyticsSelectors['header-label']
       )}
-      role="button"
-      tabIndex={0}
-      aria-label={ariaLabel}
-      aria-labelledby={!ariaLabel && description ? id : undefined}
-      aria-describedby={description ? descriptionId : undefined}
-      aria-controls={ariaControls}
-      aria-expanded={expanded}
-      {...headerButtonListeners}
-      {...headerButtonMotionTrigger}
-      {...(headerButtonListeners ? getExpandActionAnalyticsMetadataAttribute(expanded) : {})}
     >
-      {renderIconOutsideHeader ? (
-        textElement
-      ) : iconAtEnd ? (
-        <>
-          {textElement}
-          {expandIcon}
-        </>
-      ) : (
-        <>
-          {expandIcon}
-          {textElement}
-        </>
-      )}
+      {children}
     </span>
   );
+  const headerButton =
+    renderIconOutsideHeader && hideText ? (
+      textElement
+    ) : (
+      <span
+        className={clsx(
+          styles['expand-button'],
+          isContainer ? styles['header-container-button'] : styles['header-button'],
+          iconAtEnd && styles['header-button-icon-end'],
+          headerButtonListeners && styles['click-target']
+        )}
+        role="button"
+        tabIndex={0}
+        aria-label={ariaLabel}
+        aria-labelledby={!ariaLabel && (hideText || description) ? id : undefined}
+        aria-describedby={ariaDescribedBy}
+        aria-controls={ariaControls}
+        aria-expanded={expanded}
+        {...headerButtonListeners}
+        {...headerButtonMotionTrigger}
+        {...(headerButtonListeners ? getExpandActionAnalyticsMetadataAttribute(expanded) : {})}
+      >
+        {renderIconOutsideHeader ? (
+          textElement
+        ) : iconAtEnd ? (
+          <>
+            {textElement}
+            {expandIcon}
+          </>
+        ) : (
+          <>
+            {expandIcon}
+            {textElement}
+          </>
+        )}
+      </span>
+    );
 
   return (
     <div
@@ -378,8 +408,9 @@ const ExpandableHeaderTextWrapper = ({
             counter={headerCounter}
             info={headerInfo}
             actions={actions}
-            headingTagOverride={headingTagOverride}
+            headingTagOverride={hideText ? 'div' : headingTagOverride}
             __inExpandableSection={true}
+            __additionalTitleContent={secondaryContent ? <span id={describedById}>{secondaryContent}</span> : undefined}
           >
             {headerButton}
           </InternalHeader>
@@ -390,18 +421,25 @@ const ExpandableHeaderTextWrapper = ({
           <div
             className={clsx(
               styles['header-content'],
-              actions && styles['header-actions-wrapper'],
+              (actions || secondaryContent) && styles['header-actions-wrapper'],
               endInfo && styles['header-content-with-info']
             )}
           >
-            <HeadingTag
-              className={clsx(styles['header-wrapper'], headingTagListeners && styles['click-target'])}
-              {...headingTagListeners}
-              {...headingTagMotionTrigger}
-              {...(headingTagListeners ? getExpandActionAnalyticsMetadataAttribute(expanded) : {})}
-            >
-              {headerButton}
-            </HeadingTag>
+            <div className={styles['header-main']}>
+              <HeadingTag
+                className={clsx(styles['header-wrapper'], headingTagListeners && styles['click-target'])}
+                {...headingTagListeners}
+                {...headingTagMotionTrigger}
+                {...(headingTagListeners ? getExpandActionAnalyticsMetadataAttribute(expanded) : {})}
+              >
+                {headerButton}
+              </HeadingTag>
+              {secondaryContent && (
+                <div id={describedById} className={styles['header-secondary-content']}>
+                  {secondaryContent}
+                </div>
+              )}
+            </div>
             {endInfo}
             {actions}
           </div>
@@ -424,6 +462,9 @@ export const ExpandableSectionHeader = ({
   headerCounter,
   headerInfo,
   headerActions,
+  headerSecondaryContent,
+  secondaryContentId,
+  hideHeaderText,
   headingTagOverride,
   expanded,
   ariaControls,
@@ -472,6 +513,24 @@ export const ExpandableSectionHeader = ({
     warnOnce(componentName, `The \`headerActions\` prop is only supported for the "container" and "default" variants.`);
   }
 
+  if (headerSecondaryContent && !variantSupportsHeaderSecondaryContent(variant) && isDevelopment) {
+    warnOnce(
+      componentName,
+      `The \`headerSecondaryContent\` prop is only supported for the "container" and "default" variants.`
+    );
+  }
+
+  if (hideHeaderText && !headerText && isDevelopment) {
+    warnOnce(componentName, 'The `hideHeaderText` prop requires `headerText` to be set.');
+  }
+
+  if (hideHeaderText && !variantSupportsHeaderSecondaryContent(variant) && isDevelopment) {
+    warnOnce(
+      componentName,
+      `The \`hideHeaderText\` prop is only supported for the "container" and "default" variants.`
+    );
+  }
+
   if (headerDescription && !variantSupportsDescription(variant) && isDevelopment) {
     warnOnce(componentName, `The \`headerDescription\` prop is not supported for the ${variant} variant.`);
   }
@@ -504,7 +563,10 @@ export const ExpandableSectionHeader = ({
           className,
           wrapperClassName,
           expanded && styles.expanded,
-          !expanded && (!headerActions || headerDescription) && styles['wrapper-not-expanded-without-actions']
+          !expanded &&
+            (!headerActions || headerDescription) &&
+            !(headerSecondaryContent && variantSupportsHeaderSecondaryContent(variant)) &&
+            styles['wrapper-not-expanded-without-actions']
         )}
         descriptionId={descriptionId}
         headerDescription={headerDescription}
@@ -512,6 +574,9 @@ export const ExpandableSectionHeader = ({
         headerInfo={headerInfo}
         headerActions={headerActions}
         headerEndInfo={headerEndInfo}
+        headerSecondaryContent={headerSecondaryContent}
+        secondaryContentId={secondaryContentId}
+        hideHeaderText={hideHeaderText}
         headingTagOverride={headingTagOverride}
         onKeyUp={onKeyUp}
         onKeyDown={onKeyDown}
diff --git a/src/expandable-section/interfaces.ts b/src/expandable-section/interfaces.ts
index 89d6359e9fb..728dab5d217 100644
--- a/src/expandable-section/interfaces.ts
+++ b/src/expandable-section/interfaces.ts
@@ -110,4 +110,17 @@ export interface ExpandableSectionProps extends BaseComponentProps {
    * Actions for the header. Use with the default or container, default, inline or stacked variants.
    */
   headerActions?: React.ReactNode;
+
+  /**
+   * Secondary content displayed next to the header text, such as an interactive control or supporting text.
+   * Use with the default or container variant.
+   */
+  headerSecondaryContent?: React.ReactNode;
+
+  /**
+   * Visually hides the header text while keeping it available to assistive technology.
+   * Use with `headerSecondaryContent` to present a purely interactive header control.
+   * Use with the default or container variant.
+   */
+  hideHeaderText?: boolean;
 }
diff --git a/src/expandable-section/internal.tsx b/src/expandable-section/internal.tsx
index 33aa9c14d85..038b57536a2 100644
--- a/src/expandable-section/internal.tsx
+++ b/src/expandable-section/internal.tsx
@@ -17,7 +17,7 @@ import { ExpandableSectionContainer } from './expandable-section-container';
 import { ExpandableSectionHeader } from './expandable-section-header';
 import { ExpandableSectionProps } from './interfaces';
 import { InternalVariant } from './internal-interfaces';
-import { variantSupportsDescription } from './utils';
+import { variantSupportsDescription, variantSupportsHeaderSecondaryContent } from './utils';
 
 import analyticsSelectors from './analytics-metadata/styles.css.js';
 import styles from './styles.css.js';
@@ -63,6 +63,8 @@ export default function InternalExpandableSection({
   headerDescription,
   headerInfo,
   headerActions,
+  headerSecondaryContent,
+  hideHeaderText,
   headingTagOverride,
   disableContentPaddings,
   headerAriaLabel,
@@ -79,6 +81,7 @@ export default function InternalExpandableSection({
   const controlId = useUniqueId();
   const triggerControlId = `${controlId}-trigger`;
   const descriptionId = `${controlId}-description`;
+  const secondaryContentId = `${controlId}-secondary`;
 
   const baseProps = getBaseProps(props);
   const [expanded, setExpanded] = useControllable(controlledExpanded, onChange, defaultExpanded, {
@@ -138,12 +141,20 @@ export default function InternalExpandableSection({
   // Map stacked variant to container to avoid code duplication
   const baseVariant: InternalVariant = variant === 'stacked' ? 'container' : variant;
 
+  const headerTextHidden = hideHeaderText && variantSupportsHeaderSecondaryContent(baseVariant);
+
   return (
     <ExpandableSectionContainer
       {...props}
       expanded={expanded}
       className={clsx(baseProps.className, styles.root, analyticsSelectors.root)}
       variant={variant}
+      {...(headerTextHidden
+        ? {
+            role: 'region',
+            ...(headerAriaLabel ? { ariaLabel: headerAriaLabel } : { ariaLabelledby: triggerControlId }),
+          }
+        : {})}
       __injectAnalyticsComponentMetadata={__injectAnalyticsComponentMetadata}
       header={
         <ExpandableSectionHeader
@@ -163,6 +174,9 @@ export default function InternalExpandableSection({
           headerCounter={headerCounter}
           headerInfo={headerInfo}
           headerActions={headerActions}
+          headerSecondaryContent={headerSecondaryContent}
+          secondaryContentId={secondaryContentId}
+          hideHeaderText={hideHeaderText}
           headingTagOverride={headingTagOverride}
           expandIconPosition={__expandIconPosition}
           hideExpandIcon={__hideExpandIcon}
diff --git a/src/expandable-section/styles.scss b/src/expandable-section/styles.scss
index 26536293267..63a6a4982b6 100644
--- a/src/expandable-section/styles.scss
+++ b/src/expandable-section/styles.scss
@@ -246,6 +246,30 @@ $nav-caret-pad-one-theme: 12px; // 24px minus the one-theme x-small (12px) icon
     min-inline-size: 0;
   }
 
+  &-main {
+    display: flex;
+    flex-direction: row;
+    flex-wrap: wrap;
+    align-items: center;
+    column-gap: awsui.$space-xs;
+    row-gap: awsui.$space-scaled-xxs;
+    min-inline-size: 0;
+
+    > .header-wrapper {
+      flex: 1 1 auto;
+      min-inline-size: 0;
+    }
+  }
+
+  &-secondary-content {
+    display: inline-flex;
+    align-items: center;
+    flex-shrink: 0;
+    min-inline-size: 0;
+    max-inline-size: 100%;
+    margin-inline-end: auto;
+  }
+
   &-button,
   &-container-button {
     @include focus-visible.when-visible {
@@ -325,9 +349,17 @@ $nav-caret-pad-one-theme: 12px; // 24px minus the one-theme x-small (12px) icon
 
   &-text {
     /* used in test-utils */
+
+    &-hidden {
+      @include styles.awsui-util-hide;
+    }
   }
 }
 
+.header-container-button:has(> .header-text-hidden) > .icon-container {
+  margin-inline-end: 0;
+}
+
 // Make sure that actions can wrap for default expandable section headers.
 // The compact variant is used in chart popovers and should not wrap.
 :not(.wrapper-compact) > .header-actions-wrapper {
diff --git a/src/expandable-section/utils.ts b/src/expandable-section/utils.ts
index 528a60ed6c5..8b3fae3a116 100644
--- a/src/expandable-section/utils.ts
+++ b/src/expandable-section/utils.ts
@@ -12,6 +12,10 @@ export function variantSupportsActions(variant: InternalVariant) {
   return variantIsOneOf(variant, ['container', 'compact', 'default', 'inline']);
 }
 
+export function variantSupportsHeaderSecondaryContent(variant: InternalVariant) {
+  return variantIsOneOf(variant, ['container', 'default']);
+}
+
 export function variantSupportsInfoLink(variant: InternalVariant) {
   return variantIsOneOf(variant, ['container', 'compact']);
 }
diff --git a/src/header/__tests__/header.test.tsx b/src/header/__tests__/header.test.tsx
index 5634e2e6af3..72f433c85ac 100644
--- a/src/header/__tests__/header.test.tsx
+++ b/src/header/__tests__/header.test.tsx
@@ -62,6 +62,18 @@ test('supports title tag name override', () => {
   expect(wrapper.getElement()).toHaveClass(styles['root-variant-h2']);
 });
 
+test('supports overriding the title tag with h6', () => {
+  const { wrapper } = renderHeader(<Header headingTagOverride="h6">title</Header>);
+  expect(wrapper.find('h2')).toBeNull();
+  expect(wrapper.find('h6')!.getElement()).toHaveTextContent('title');
+});
+
+test('renders the title without heading semantics when overridden to div', () => {
+  const { wrapper } = renderHeader(<Header headingTagOverride="div">title</Header>);
+  expect(wrapper.find('h1,h2,h3,h4,h5,h6')).toBeNull();
+  expect(wrapper.findHeadingText().getElement()).toHaveTextContent('title');
+});
+
 test('renders h1 variant', () => {
   const { wrapper } = renderHeader(<Header variant="h1">title</Header>);
   expect(wrapper.find('h1')!.getElement()).toHaveTextContent('title');
diff --git a/src/header/interfaces.ts b/src/header/interfaces.ts
index de2754fde51..08731b3a9e9 100644
--- a/src/header/interfaces.ts
+++ b/src/header/interfaces.ts
@@ -22,7 +22,8 @@ export interface HeaderProps extends BaseComponentProps {
   variant?: HeaderProps.Variant;
   /**
    * Overrides the default [HTML heading tag](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements)
-   * provided by the variant. Using this property does not change the visual appearance of the component.
+   * provided by the variant. Set to `div` to render the title without heading semantics. Using this property does not
+   * change the visual appearance of the component.
    */
   headingTagOverride?: HeaderProps.HeadingTag;
   /**
@@ -46,5 +47,5 @@ export interface HeaderProps extends BaseComponentProps {
 
 export namespace HeaderProps {
   export type Variant = 'h1' | 'h2' | 'h3' | 'awsui-h1-sticky';
-  export type HeadingTag = 'h1' | 'h2' | 'h3' | 'h4' | 'h5';
+  export type HeadingTag = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'div';
 }
diff --git a/src/header/internal.tsx b/src/header/internal.tsx
index 1a42ac1010c..24d37f7095b 100644
--- a/src/header/internal.tsx
+++ b/src/header/internal.tsx
@@ -27,6 +27,11 @@ interface InternalHeaderProps extends SomeRequired<HeaderProps, 'variant'>, Inte
   __headingTagRef?: MutableRefObject<HTMLHeadingElement | null>;
   __headingTagTabIndex?: number;
   __inExpandableSection?: boolean;
+  /**
+   * Rendered in the title row but outside the heading tag, so content beside the title is not
+   * nested inside the heading element.
+   */
+  __additionalTitleContent?: React.ReactNode;
 }
 
 export default function InternalHeader({
@@ -42,6 +47,7 @@ export default function InternalHeader({
   __headingTagRef,
   __headingTagTabIndex,
   __inExpandableSection,
+  __additionalTitleContent,
   ...restProps
 }: InternalHeaderProps) {
   const isMobile = useMobile();
@@ -118,6 +124,9 @@ export default function InternalHeader({
             </InfoLinkLabelContext.Provider>
           )}
         </div>
+        {__additionalTitleContent && (
+          <div className={styles['additional-title-content']}>{__additionalTitleContent}</div>
+        )}
         {actions && (
           <div
             className={clsx(
diff --git a/src/header/styles.scss b/src/header/styles.scss
index 9bfabedbc7b..b4b203f5be1 100644
--- a/src/header/styles.scss
+++ b/src/header/styles.scss
@@ -130,6 +130,15 @@
   }
 }
 
+.additional-title-content {
+  display: inline-flex;
+  align-items: center;
+  flex-shrink: 0;
+  min-inline-size: 0;
+  max-inline-size: 100%;
+  margin-inline-end: auto;
+}
+
 .title {
   @include styles.text-wrapping;
   color: awsui.$color-text-heading-default;
@@ -178,6 +187,19 @@
   }
 }
 
+// With secondary content beside the heading, center both against a constant-height line so their
+// alignment no longer shifts when actions wrap to a second row.
+.main:has(> .additional-title-content) > .title-variant-h2.title-in-expandable-section.refresh {
+  padding-block-start: 0;
+  min-block-size: awsui.$size-vertical-input;
+  display: flex;
+  align-items: center;
+
+  @include theming.one-theme-only {
+    min-block-size: calc(#{awsui.$size-vertical-input} - 2 * #{awsui.$border-width-button});
+  }
+}
+
 .root-no-actions.root-has-description > .main > :not(.refresh) {
   &.title-variant-h2,
   &.title-variant-h3 {