Heading
<gcds-heading>

Also called: title, section heading, subheading.

A heading is a title that establishes levels of hierarchy to organize page content into a structure.

• GitHub
• Figma

On this page

• Coding and accessibility for headings
• Examples
• Code builder

Coding and accessibility for headings

Order heading levels hierarchically

Heading levels follow a sequential, hierarchical order: higher levels have larger display text than lower ones.

• Set correct and consistent heading levels to align the coded and visual headings on a page. Consistent headings support an equitable experience for people who use assistive technologies.
• Order headings sequentially from lowest to highest (H1–H6).
• Avoid skipping heading levels. Instead, restructure content so headings are used sequentially, from largest (H1) to smallest (H6).
• Only use an H1 heading once on a page. Other heading types can be used multiple times.
• Use H2 headings to describe individual sections. Each section should have one H2 heading.
• Opt to use H3–H6 headings within sections. Sections can contain multiple H3–H6 headings, as long as they are placed in hierarchical order.

Maintain accessible character limits

• Maintain the default character-limit for each heading line by keeping the attribute set to true for a comfortable and accessible reading length. These defaults create a balanced, consistent line length across heading font sizes.
• Keep character limits to the following lengths to maintain a visual balance across headings on a page:
  • 31 characters for H1.
  • 35 characters for H2.
  • 40 characters for H3.
  • 45 characters for H4.
  • 50 characters for H5.
  • 57 characters for H6.

Use consistent spacing

• Maintain default spacing for a comfortable and accessible reading experience. These defaults create visual breaks and separation between different sections.
• Keep spacing values to the following to maintain a visual balance across headings on a page:
  • Default margin-bottom: 300 for all
  • Default margin-top: 0 for H1 and 600 for H2–6

In this section

• Essential attributes
• Optional attributes
• Slots

tag

The tag attribute sets the appropriate HTML heading element for the selected level.

<gcds-heading tag="h2">
  Heading
</gcds-heading>

character-limit

The character-limit attribute defines the line length to a maximum number of characters per line for each heading level, ensuring a comfortable, accessible reading length.

<gcds-heading tag="h2" character-limit="false">
  Heading
</gcds-heading>

heading-role

The heading-role attribute sets the main style of the heading. The available options are:

• primary (default)
• secondary
• light

<gcds-heading tag="h2" heading-role="secondary">
  Heading
</gcds-heading>

margin-bottom

The margin-bottom attribute sets a margin below the heading. The default margin-bottom is 300.

<gcds-heading tag="h2" margin-bottom="600">
  Heading
</gcds-heading>

margin-top

The margin-top attribute sets a margin above the heading. The default margin-top for h1 is set to 0, while for h2 to h6 headings, it's 600.

<gcds-heading tag="h2" margin-top="200">
  Heading
</gcds-heading>

default

The default slot is for adding text to the heading.

<gcds-heading tag="h2">
  Heading
</gcds-heading>

Code builder

Generate an instance of the component you need by selecting its code properties.

1. Explore by choosing different code values to generate the instance you want.

2. Get the code and pull it into your environment.

3. Add any copy you need to the component (like text for a label).

Note: The code builder uses English for all code elements, which follows standard practice.