Allow restriction of the heading levels available in the heading block

[michaelmcandrew]

What problem does this address?

Currently the heading block allows users to insert any heading level from 1 to 6. This is nice and flexible but in some instances, it would be good to be able to restrict this, for example, only allow 2-6 or 2-3 (in the same way that we can restrict spacing, colours, remove blocks etc.).

In the current implementation, the list of headings is hard coded here: https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/heading/heading-level-dropdown.js#L12 and cannot be adjusted.

What is your proposed solution?

One solution would be to use the theme.json settings mechanism to implement a new setting (maybe under typography?) called headingLevels, which would be an array that would some or all of the numbers between 1 and 6.

We can then use this array (if it exists) instead of the hard coded array in block-library/src/heading/heading-level-dropdown.js.

The only thing that gives me pause about this approach is that core/heading is the only block that this setting would get applied to. This struck me as odd at first, but on reflection, I don't think it is a big deal. After all there is no rule that says settings need to apply to multiple blocks and AFAIK, there is not a method for defining a setting for a particular block.

Thinking about alternative approaches, I wondered if a block hook (e.g. editor.BlockEdit might be able to help. Perhaps in conjunction with adding an extra prop to the component. Not sure if this is a good approach or there is a precedent for doing it this way in Gutenberg.

And maybe there is another approach I am not thinking of. How have we solved similar problems in the past?

PS. see https://wordpress.org/support/topic/gutenberg-headings-block-remove-h1-h3-etc-as-options/ and https://wordpress.stackexchange.com/questions/405558/restrict-heading-level-in-gutenberg-block-core-heading #15160 #13565 for some other people trying to do the same thing.

[ALJ]

I agree; theme developers should be given the flexible ability to allow and disallow heading levels. It's such a common need when working on controlled design systems that its exclusion from the block editor is a recurring headache on the projects I see.

I suggest heading levels should be (dis)allowed by the context of the heading blocks. I.e. a parent block should declare which heading levels are allowed inside it.

Rarely do I want to disallow all heading levels 5 and 6 site-wide. Instead, I want to disallow heading levels 1, 5, and 6 inside a particular container block, but still allow them elsewhere, like in default post_content. Perhaps this could be done by expanding the existing allowedBlocks property, e.g.:

<InnerBlocks allowedBlocks={ [ 'core/heading/h2', 'core/heading/h3' ] } />;

@michaelmcandrew some ideas if you need to control heading levels now:

1. See this comment for how to hide the heading level buttons in the block editor toolbar via CSS.
2. Consider making your own custom blocks, one for each heading level. Then, remove the core/heading block and allow your custom block(s) where you wish.

[michaelmcandrew]

I suggest heading levels should be (dis)allowed by the context of the heading blocks. I.e. a parent block should declare which heading levels are allowed inside it.

@ALJ - since there are likely lots of different opinions views on how heading levels should be restricted it might make sense to limit issue to just enabling the customization. We can then leave exactly when and how it happens to others (e.g. theme / plugin authors).

@marceloaof - thanks for listing those other blocks - I forgot about them!

It looks like all of them apart from use the HeadingLevelDropdown component apart from core/site-title which has its own dropdown. For those that use the HeadingLevelDropdown component, filtering the list based on a setting seems straight forward.

We could use the same setting to filter the list here https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/site-title/edit/level-toolbar.js#L13, or it could be out of scope for this issue.

Also @marceloaof - core/archive-title doesn't seem to exist - but core/query-title is used for this purpose, I think.

The settings API does feel like a good way to do this to me but I have only been using Gutenberg since late last year and have not contributed to it yet so I may well be missing something and am interested in feedback from others.

[ALJ]

@michaelmcandrew for a bit more visibility, consider adding your voice and suggested solutions to the older issue at #20213 as this one is a (potential) dupe.

[skorasaurus]

Thanks for your clear description @michaelmcandrew . This is a duplicate of #20213 where you can track its progress.