Heading Block

Start here: watch the walkthrough (19 minutes)

Why use the Heading block

You’ll use the Heading block any time you want to:

• Break content into clear, scannable sections
• Create a logical hierarchy on a page
• Improve readability for all users
• Support accessibility tools like screen readers
• Help search engines understand page structure

Think of headings as the outline of your page. Even if someone never reads every word, headings help them understand what the page is about and where to find what they need.

---

How to use the block

Start by adding the Heading block to the page. Learn how to add blocks.

Once the block is added, editors typically:

• Enter the heading text
• Choose the appropriate heading level
• Adjust alignment in the block toolbar
• Apply styles to control visual size without changing structure

This block is all about structure first, styling second.

---

Block toolbar

The block toolbar appears above the Heading block when it’s selected.

Available options

• Heading level: Choose H1–H6.
• Text alignment: Left, center, or right.
• Block width: Control how wide the heading appears within the layout.
• Bold / Italic: Apply emphasis to text.
• Link: Turn the heading text into a link when needed.

---

Block settings

While editing the block, the right sidebar panel includes additional block settings.

Use balanced text

Distributes text evenly across multiple lines to create a more visually balanced heading. This is especially useful for longer headings or large display styles.

Note: Balanced Text works on content up to 4 lines in length. Due to browser limitations, if the content exceeds 4 lines, the balanced text will not apply.

Use hanging punctuation

Aligns opening punctuation marks (like quotation marks) outside the text block. This creates a cleaner visual edge, particularly in large headings.

Decorative heading

Turns the heading into a purely visual element by using a <div> instead of a semantic heading tag.

Notes:

• Decorative Headings should not be used for real content structure.
• This option is intended for design-only text that should be ignored by accessibility tools. If you’re unsure whether a heading should be decorative, it probably shouldn’t be.
• When enabled, you must apply a Style. Do not use the Default size when this option is active.

---

Block styles

In Block Settings, the Styles tab includes additional controls to adjust the appearance of the Heading block.

Styles

Style options let you keep the correct heading level for accessibility while adjusting the visual size. This helps you meet design needs without breaking the heading hierarchy. This flexibility helps you avoid using incorrect heading levels just to achieve a certain look. The Default style uses the standard font size for that heading level, as defined by the site’s design system, with additional options ranging from XX Small to X Large.

Text color

Choose from available color options to ensure sufficient contrast and brand consistency. The options are pre-defined according to your site’s design system.

Padding and margin

Adjust spacing around the heading to improve layout flow. Control top, bottom, left, and right values independently.

---

Accessibility and content structure

Heading levels aren’t just about size — they communicate meaning and structure.

How heading levels work

• Heading 1 (H1): The main title of the page. There should usually be only one H1 per page.
• Heading 2 (H2): Major sections of the page.
• Heading 3 (H3): Subsections within an H2.
• Heading 4–6 (H4–H6): Deeper levels of detail, used sparingly.

Best practices for nesting headings

• Headings should be nested in order. Don’t skip levels (for example, jumping from H2 directly to H4 is an accessibility violation).
• Choose heading levels based on content structure, not how big or small the text looks.
• Use Styles (see below) to adjust visual size if needed — without breaking the heading hierarchy.

This structure is critical for screen reader users, who often navigate pages by heading level instead of scrolling.

---

Tips for editors

Even experienced editors can run into issues with headings. These tips cover the most common pitfalls — and how to avoid them.

Don’t skip heading levels

Headings should be nested in order. Jumping from an H2 straight to an H4 breaks the page structure for screen readers. Choose the correct heading level first, then adjust the Style if the text size needs to look bigger or smaller.

Use headings for structure, not styling

Headings aren’t just large text. They define sections and help users navigate the page. Use headings only for section titles. For visual emphasis elsewhere, use paragraph text and Styles instead.

Be careful with decorative headings

Decorative Headings remove semantic meaning and should be used sparingly. Only use Decorative Heading for purely visual elements. If the text introduces or organizes content, use a real heading.

Avoid multiple H1s

Most pages should have a single H1 that represents the main topic. Let the page title handle the H1 when possible. Start your content with H2s unless there’s a clear reason not to.

---

Related learning resources

1. WordPress.org Heading Block documentation. Please note that your block may have customizations affecting the functionality, appearance and settings.