Headings element

For basic heading formatting and sizes.

github location npm version

Usage

EMBL’s primary corporate typeface is IBM Plex Sans. Subdomains should use the same font except for cases where they have a different brand guideline.

The vf-heading component leverages the design token typography sizes.

Use heading tags, such as <h1> and <h2> to define the structure of a page. Apply tokens, such as vf-text-heading--1 to define the size and other stylistic elements of the heading.

To establish a consistent content organisation throughout your site, style headings consistently. However, a heading level such as <h1> does not always need to correspond with the same token such as vf-text-heading--1. You can change the token if the page requires so but it is advisable to ensure the pages have a consistent heading structure whenever possible.

This component provides utility-like functionality and you'll rarely need to directly use this component. When coding a component's Sass, it will typically be better to use the mixins (@include set-type(text-heading--1);) than these vf-heading classes.

How to use

  • Every page should have at least one heading (typically a h1).
  • All text that looks like a heading should be marked up as a heading.
  • All text that is marked up as a heading should be a conceptual section heading.
  • The heading hierarchy should be meaningful, e.g: <h1>Recruitment: What to expect</h1> <h2>Our recruitment process</h2> <h3>Step 1: Application</h3>

Headings should be written in sentence case.

How not to use

  • Do not skip heading levels (e.g. from <h1> to <h3> without a <h4> on a page) as this causes issues to users of screen readers and other assistive technologies.
  • Do not use headings to style text that is not meant to be a heading element. Use a different vf-text style instead of a heading level for this type of text.

Related documentation

For more information on headings please consult the following documents:

Variants

Heading Level 1 variant

This is heading 1

Nunjucks syntax

Depending on your environment you'll want to use render or include. As a rule of thumb: server-side use include, precompiled browser use render. If you're using vf-eleventy you should use include.

Using include

You'll need to pass a context object from your code or Yaml file (example), as well as the path to the Nunjucks template. Nunjucks' include is an abstraction of render and provides some additional portability.


{% set context fromYourYamlFile %}
- or -
{% set context = { 
"component-type" : "element",
"exampleMultiColumns" : true,
"type" : 1,
"heading" : "This is heading 1",
"tags" : "h1",
 }
%}
{% include "../path_to/vf-heading/vf-heading.njk" %}

Using render

This approach is best for bare-bones Nunjucks environments, such as precompiled templates with the Nunjucks slim runtime where include is not be available.


{% render '@vf-heading', {
  "component-type" : "element",
  "exampleMultiColumns" : true,
  "type" : 1,
  "heading" : "This is heading 1",
  "tags" : "h1",}
%}
HTML 
 <h1 class="vf-text vf-text-heading--1">This is heading 1</h1>

Heading Level 2 variant

This is heading 2

Nunjucks syntax

Depending on your environment you'll want to use render or include. As a rule of thumb: server-side use include, precompiled browser use render. If you're using vf-eleventy you should use include.

Using include

You'll need to pass a context object from your code or Yaml file (example), as well as the path to the Nunjucks template. Nunjucks' include is an abstraction of render and provides some additional portability.


{% set context fromYourYamlFile %}
- or -
{% set context = { 
"component-type" : "element",
"type" : 2,
"heading" : "This is heading 2",
"tags" : "h2",
 }
%}
{% include "../path_to/vf-heading/vf-heading.njk" %}

Using render

This approach is best for bare-bones Nunjucks environments, such as precompiled templates with the Nunjucks slim runtime where include is not be available.


{% render '@vf-heading', {
  "component-type" : "element",
  "type" : 2,
  "heading" : "This is heading 2",
  "tags" : "h2",}
%}
HTML 
 <h2 class="vf-text vf-text-heading--2">This is heading 2</h2>

Heading Level 3 variant

This is heading 3

Nunjucks syntax

Depending on your environment you'll want to use render or include. As a rule of thumb: server-side use include, precompiled browser use render. If you're using vf-eleventy you should use include.

Using include

You'll need to pass a context object from your code or Yaml file (example), as well as the path to the Nunjucks template. Nunjucks' include is an abstraction of render and provides some additional portability.


{% set context fromYourYamlFile %}
- or -
{% set context = { 
"component-type" : "element",
"type" : 3,
"heading" : "This is heading 3",
"tags" : "h3",
 }
%}
{% include "../path_to/vf-heading/vf-heading.njk" %}

Using render

This approach is best for bare-bones Nunjucks environments, such as precompiled templates with the Nunjucks slim runtime where include is not be available.


{% render '@vf-heading', {
  "component-type" : "element",
  "type" : 3,
  "heading" : "This is heading 3",
  "tags" : "h3",}
%}
HTML 
 <h3 class="vf-text vf-text-heading--3">This is heading 3</h3>

Heading Level 4 variant

This is heading 4

Nunjucks syntax

Depending on your environment you'll want to use render or include. As a rule of thumb: server-side use include, precompiled browser use render. If you're using vf-eleventy you should use include.

Using include

You'll need to pass a context object from your code or Yaml file (example), as well as the path to the Nunjucks template. Nunjucks' include is an abstraction of render and provides some additional portability.


{% set context fromYourYamlFile %}
- or -
{% set context = { 
"component-type" : "element",
"type" : 4,
"heading" : "This is heading 4",
"tags" : "h4",
 }
%}
{% include "../path_to/vf-heading/vf-heading.njk" %}

Using render

This approach is best for bare-bones Nunjucks environments, such as precompiled templates with the Nunjucks slim runtime where include is not be available.


{% render '@vf-heading', {
  "component-type" : "element",
  "type" : 4,
  "heading" : "This is heading 4",
  "tags" : "h4",}
%}
HTML 
 <h4 class="vf-text vf-text-heading--4">This is heading 4</h4>

Heading Level 5 variant

This is heading 5
Nunjucks syntax

Depending on your environment you'll want to use render or include. As a rule of thumb: server-side use include, precompiled browser use render. If you're using vf-eleventy you should use include.

Using include

You'll need to pass a context object from your code or Yaml file (example), as well as the path to the Nunjucks template. Nunjucks' include is an abstraction of render and provides some additional portability.


{% set context fromYourYamlFile %}
- or -
{% set context = { 
"component-type" : "element",
"type" : 5,
"heading" : "This is heading 5",
"tags" : "h5",
 }
%}
{% include "../path_to/vf-heading/vf-heading.njk" %}

Using render

This approach is best for bare-bones Nunjucks environments, such as precompiled templates with the Nunjucks slim runtime where include is not be available.


{% render '@vf-heading', {
  "component-type" : "element",
  "type" : 5,
  "heading" : "This is heading 5",
  "tags" : "h5",}
%}
HTML 
 <h5 class="vf-text vf-text-heading--5">This is heading 5</h5>

Examples

Installation info

This component is distributed with npm. After installing npm, you can install the vf-heading with this command.

$ yarn add --dev @visual-framework/vf-heading

Sass/CSS

The source files included are written in Sass(scss). You can point your Sass include-path at your node_modules directory and import it like this.

@import "@visual-framework/vf-heading/index.scss";

Make sure you import Sass requirements along with the modules. You can use a project boilerplate or the vf-sass-starter

Changelog

Changelog

1.1.1

  • Documentation: Detailed documentation added Tracking issue
  • Updated: Naming convention updated as per design recommendations Tracking issue

1.1.0

  • Changes of name of variants to reflect connection to design tokens.
  • https://github.com/visual-framework/vf-core/issues/1661

1.0.1

  • changes any set- style functions to cleaner version

1.0.0

  • Initial stable release

Assets


File system location: components/vf-heading

Find an issue on this page? Propose a change or discuss it.