HTML headingoffset Attribute

HTML headingoffset Attribute

The HTML headingoffset global attribute increases the computed heading level of heading elements within an element without changing the <h1> through <h6> elements used in the markup. It can help reusable content or components fit into different heading levels within a document.

Syntax

The headingoffset attribute takes a non-negative integer from 0 through 8. The value is added to the computed heading level of headings within the element.

<section headingoffset="1">
  <h1>Section Heading</h1>
</section>

Although the heading remains an <h1> element in the HTML, its computed heading level is 2.

Global Attribute

The headingoffset attribute is a global attribute and can be specified on HTML elements. Its effect is relevant to heading elements within the element on which it is specified, including the element itself when that element is a heading.

<article headingoffset="2">
  <h1>Article Heading</h1>
  <p>Article content.</p>
</article>

Here, the <h1> has a computed heading level of 3 because the offset of 2 is added to its normal level of 1.

Attribute Values

The value of headingoffset must be a valid non-negative integer between 0 and 8, inclusive.

If the value cannot be parsed as a valid non-negative integer, it contributes an offset of 0. A conforming headingoffset value must not be greater than 8.

Computed Heading Level

Without an offset, an <h1> has a computed heading level of 1, an <h2> has a level of 2, and so on. The headingoffset value is added to that normal level.

<section headingoffset="2">
  <h1>Computed Level 3</h1>
  <h2>Computed Level 4</h2>
</section>

The first heading has a computed level of 3 and the second has a computed level of 4. The actual HTML elements remain <h1> and <h2>, so their element names and default visual styling do not change.

A computed heading level is capped at 9, even when the heading's normal level plus accumulated offsets would produce a higher number.

Nested Offsets

Offsets accumulate when elements with headingoffset are nested. The browser adds the applicable offsets from the heading and its ancestors.

<article headingoffset="1">
  <section headingoffset="2">
    <h2>Computed Level 5</h2>
  </section>
</article>

The <h2> normally has a level of 2. The outer offset adds 1 and the inner offset adds 2, resulting in a computed heading level of 5.

Using headingreset

The headingreset attribute stops heading-offset calculations from continuing beyond the element on which it appears. This allows content such as a dialog or reusable component to establish heading levels independently of offsets applied by more distant ancestors.

<section headingoffset="2">
  <h1>Computed Level 3</h1>

  <dialog open headingreset>
    <h1>Computed Level 1</h1>
  </dialog>
</section>

The section's offset applies to its first heading, but headingreset prevents that ancestor offset from affecting the heading inside the dialog.

Accessibility

Heading levels help assistive technologies communicate the structure of a page. The headingoffset attribute can allow reusable markup to expose heading levels that match where the content appears within a larger document structure.

Because browser support is currently limited, the underlying <h1> through <h6> markup should still provide a meaningful structure when headingoffset is not supported. An explicit aria-level on a heading takes precedence over its computed heading level.

Common Mistakes

Do not use headingoffset merely to change the visual size of a heading. Use CSS when the goal is only to change how a heading looks.

Do not assume that headingoffset changes an <h1> into another heading element. The element remains an <h1>; only its computed heading level changes.

Remember that nested offsets accumulate. Consider all applicable ancestor offsets when determining the resulting computed heading level.

Because support is not yet available in every core browser, do not rely on headingoffset as the only way to provide a meaningful heading structure.

Browser Support

Baseline: Limited availability indicates that a feature is not yet available in all core browsers. Use these features with caution because they may only work in select browsers, so additional compatibility checks may be needed before general use.

The headingoffset global attribute has limited availability and should be tested before it is relied on for document heading structure.

Checking Browser Support

For current browser compatibility information, visit Can I Use? . Search for the HTML element or attribute you want to check. You can also narrow your search by entering an element name and attribute name separated by a colon. Search results can include related HTML features, element attributes, input types, APIs, and other technologies, so select the result that most closely matches the feature you are checking.

Try the headingoffset Attribute

The example places an <h1> inside a section with headingoffset="2". The element remains an <h1>, but supporting browsers expose it with a computed heading level of 3.

Summary

The HTML headingoffset global attribute increases the computed level of headings without changing the heading elements used in the markup. Its value can range from 0 through 8, nested offsets accumulate, and the final computed heading level is capped at 9. The related headingreset attribute can prevent offsets from more distant ancestors from applying.