PanelBody: Add headingLevel prop to configure the title heading level

[Mayank-Tripathi32]

What?

Closes #26867

Adds a headingLevel prop to PanelBody so the title can render as h1–h6 instead of always being an h2. Defaults to 2, so existing usage is unchanged.

Why?

PanelBody hardcoded its title in an <h2>. When used outside the core sidebar context (e.g. plugins reflecting their own document outline), that fixed level breaks the heading hierarchy, forcing authors to fork the component. This matches the headingLevel prop already offered by ToolsPanel, ColorPalette, and GradientPicker.

How?

• Added headingLevel?: HeadingSize to PanelBodyProps / PanelBodyTitleProps (reusing the shared HeadingSize type).
• The title element is now h${ headingLevel } instead of a literal <h2>. Styling is unchanged — .components-panel__body-title is class-based with font-size: inherit, so only the tag/semantics change.

Testing Instructions

1. Storybook → PanelBody. By default the title renders as an <h2>.
2. Pass headingLevel={ 3 } and confirm the title renders as an <h3> (inspect the DOM) with unchanged visual appearance.
3. Unit tests: npm run test:unit packages/components/src/panel/test/body.tsx — includes new cases for the default level (2) and a custom level (3).

Testing Instructions for Keyboard

No interaction changes — the toggle button inside the heading behaves exactly as before.

Use of AI?

• Yes, Claude

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: Mayank-Tripathi32 <mayanktripathi32@git.wordpress.org>
Co-authored-by: ciampo <mciampini@git.wordpress.org>
Co-authored-by: Mamaduka <mamaduka@git.wordpress.org>
Co-authored-by: t-hamano <wildworks@git.wordpress.org>
Co-authored-by: mirka <0mirka00@git.wordpress.org>
Co-authored-by: johnwatkins0 <johnwatkins0@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[ciampo]

Is there a real need for this feature? The original issue doesn't highlight any, and no one else commented since its opening in 2020.

[ciampo]

Let's also test for the string version, eg '3'

[Mamaduka]

Is there a real need for this feature? The original issue doesn't highlight any, and no one else commented since its opening in 2020.

A good question to answer before moving forward. I see this component as one made for the sidebar. I think it's better to use and recommend CollapsibleCard for different cases.

[t-hamano]

Is there a real need for this feature? The original issue doesn't highlight any, and no one else commented since its opening in 2020.

In fact, I have released a React-based settings page using the Panel component.

https://wordpress.org/plugins/custom-html-block-extension/

For my use case, this plugin needed collapsible sections. At the time, the CollapsibleCard component didn’t exist, so the Panel component was the only available option.

In my case, keeping the panel heading as an h2 works perfectly fine. However, there may be other consumers using this component outside of the sidebar who would prefer to use a heading level other than h2.

[mirka]

The weird thing I'm noticing is that the Panel header is also hardcoded to render as an h2 😅

I'm not necessarily against adding heading level props to this component family, since the component is not going away. But given that any third-party need for this customization is not for the block inspector, we could maybe just say that CollapsibleCard should be used for anything outside the block inspector, and leave the Panel family as is.

[Mayank-Tripathi32]

But given that any third-party need for this customization is not for the block inspector, we could maybe just say that CollapsibleCard should be used for anything outside the block inspector, and leave the Panel family as is.

True but is it really that much work to add and maintain this for panel family? Other components have it already. I think it makes sense to have similar option in panel aswell.

[t-hamano]

If we want to recommend the use of the CollapsibleCard component instead of the Panel component going forward, we might be able to consider not extending the Panel component for now. Unless we find a specific use case where the Panel component truly requires heading level support, we could close this as 'maybe later'.

[Mamaduka]

@Mayank-Tripathi32, less code to maintain is always better; there's no real cost for this singular case, but it all adds up eventually.

I also don't see a real benefit in recommending Panel over CollapsibleCard outside the Inspector. We could add a small recommendation note to the Panel docs.

[Mayank-Tripathi32]

Understood, Lets just add the note in that case.

I can open up a PR for it later today.

[Mayank-Tripathi32]

Closing in favour of #78863