Design Tokens for Mesh have just been released!
Skip to content

Our standard heading component. Headings have no margins by default and can be sized independently of the underlying html element.

Installation

bash
npm install @nib-components/heading

Usage

jsx
import Heading from '@nib-components/heading';

Interactive demo

jsx

Props

PropTypeDefaultDescription
size (required)number or objectThe heading size. Can be made responsive by passing an object of breakpoints. Value(s) must be one of 1, 2, 3, 4, 5 or 6.
componentstring or ComponentThe heading component. What DOM element should your heading be. Optional if size is a number, required if size is an object.
colorstring or functionEach heading level has a default color defined in tokens.The heading color. Can be any of the named color tokens or theme selectors.
fontTypestringDependent on size prop. serif for size = 1, sans-serif otherwise.Switches the font-family for the heading. This only works with the nib theme. Must be one of 'sans-serif' or 'serif'. See considerations below for how size and fontType interact.
alignstring or objectSet the alignment of the text. Can be made responsive by passing an object of breakpoints. Values must be one of 'left', 'center' or 'right'.

Considerations

The Heading component should be used for all heading elements and headings should be sentence case only.

There should only ever be one h1 used on a page.

Be sure not to exceed 70 characters and avoid using hyphens (-) to line wrap text.

Font type

The Heading component supports our two brand fonts; Grenette Pro (serif) and Buenos Aires (sans-serif). The default value for font type is dependent on the size of the heading.

SizeDefault fontType
1serif
2sans-serif
3sans-serif
4sans-serif
5sans-serif
6sans-serif

Grenette Pro should be used almost exclusively for large headinngs. It should be used only for page or section headings, or where nib's brand voice is used to communicate a value proposition. See our foundational typography guidelines for more information.

Responsively sized headings

The variable default for fontType dependent on the size of the heading can lead to unexpected font-swap in one specific scenario: Commonly, a heading size of 1 is dropped down to a 2 on mobile devices to save space. In this case, the heading font will be sans-serif on mobile, and serif above the md breakpoint.

jsx

To prevent this swapping, add an explicit fontType prop:

jsx

Margins

Headings have no margins by default. To add margins to paragraphs please use our Stack layout component for consistent vertical spacing.

Heading levels

There are times when you may want to include a certain h level, but for the underlying DOM element to have a specific size. For this, our Heading component supports mixing styling and heading levels through the component prop.

This is especially important for ensuring that pages follow a logical, semantic heading hierarchy.

Responsive heading size is possible by supplying an object of breakpoints to the size prop, and specifying the underlying DOM element via the component prop.

If longer text is required, consider using the Copy component instead.