Heading
Our standard heading component. Headings have no margins by default and can be sized independently of the underlying html element.
Installation
npm install @nib-components/heading
Usage
import Heading from '@nib-components/heading';
Interactive demo
Props
| Prop | Type | Default | Description |
|---|---|---|---|
size (required) | number or object | The 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. If you are passing a responsive object, you must provide xs breakpoint value. | |
component | string or Component | The heading component. What DOM element should your heading be. Optional if size is a number, required if size is an object. | |
color | string or function | Each heading level has a default color defined in tokens. | The heading color. Can be any of the named color tokens or theme selectors. |
fontType | string | Dependent 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. |
align | string or object | Set 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.
| Size | Default fontType |
|---|---|
1 | serif |
2 | sans-serif |
3 | sans-serif |
4 | sans-serif |
5 | sans-serif |
6 | sans-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.
To prevent this swapping, add an explicit fontType prop:
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.