<Heading as="h1" variant="heading10" marginBottom="space0">Black lives matter</Heading>
Headings are words or phrases that are intended to introduce sections of content. Headings are often used for page headings, as well as content subsections within the page.
Headings should allow users to easily distinguish content sections on the page.
- Headings can have multiple levels of depth to help organize content.
- Heading types provide specific styles to the font-size, font-weight, and line-height of the text to create hierarchy that allow users to easily scan pages and content.
- Headings should be used with intention that maintains a coherent document outline.
- Don’t use heading tags to resize text. Instead use the
<Text>
primitive. - Don’t skip headline levels. Always start with
<h1>
,<h2>
, and so on. In other words, don't use an<h3>
unless preceded by an<h2>
. - There can only be one
<h1>
tag per page. - Always use sentence case when writing headings, for more information read the product style guide.
It is important to not skip one or more heading levels as it is common for screen readers to build an outline of the page and assist users as they navigate a page. Skipping a heading level could cause confusion as the user navigating the page may not know why a heading is missing.
- Heading text should meet AA requirements (4.5:1) for color contrast from itself and the background color.
- Headings should have clear hierarchies of content and subsections.
<><Heading as="h1" variant="heading10">Black lives matter</Heading><Heading as="h2" variant="heading20">Black lives matter</Heading><Heading as="h3" variant="heading30">Black lives matter</Heading><Heading as="h4" variant="heading40">Black lives matter</Heading><Heading as="h5" variant="heading50">Black lives matter</Heading><Heading as="h6" variant="heading60">Black lives matter</Heading></>
<Heading as="h2" variant="heading10">Heading one</Heading>
<Heading as="h2" variant="heading20">Heading two</Heading>
<Heading as="h2" variant="heading30">Heading three</Heading>
<Heading as="h2" variant="heading40">Heading four</Heading>
<Heading as="h2" variant="heading50">Heading five</Heading>
<Heading as="h2" variant="heading60">Heading six</Heading>
<Card><Heading as="h2" marginBottom="space0" variant="heading10">Heading with no margin</Heading></Card>
Headings should capture the most important information contained in the content beneath it. A user should be able to scan just the headers and understand the flow of information on the page.
Keep headings concise. You can omit articles ("a", "the") depending on the context. If the user would be prioritizing efficiency, leave out articles. If the content is more casual, include articles.
Use sentence case.
Visual hierarchy doesn't always follow document hierarchy. For
this reason, we've decoupled the visual appearance (the variant
prop)
from the semantic hierarchy (the as
prop) of the element.
For accessibility reasons we want to create a nice clean document hierarchy where:
- We only have one h1
- We don't skip levels as we travel the DOM:
h1
h2
h3
h3
h2
h2
h3
h4
h3
h4
Sometimes, the appropriate document level doesn't match the visual design, because, for example, the third section of content is less important than the previous two, but at the same logical level of document hierarchy.
By decoupling visual appearance from hierarchy, we enable designers and engineers to create visual and semantic hierarchy correctly for all users.
Headings should be used for page headings or content subsections. Headings are broken into six levels, where h1 is the highest level and h6 is the lowest. Avoid skipping heading levels. Use the next lowest heading level to maintain a coherent document outline.
This is sentence case
Do
Use sentence case in headings.
This Is Title Case
Don't
Don’t use title case.
Do
Use headings for page headings and to organize content on the page.
Don't
Don’t use headings for pure stylistic purposes.
Do
Use headings in order.
Don't
Don’t skip levels or put smaller headings before larger headings.
yarn add @twilio-paste/heading - or - yarn add @twilio-paste/core
import {Heading} from '@twilio-paste/core/heading';
const Component = () => (
<Heading as="h2" variant="heading20">
Heading Two
</Heading>
);
Prop | Type | Description | Default |
---|---|---|---|
as | asTags | 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'div', 'label', 'span' | null |
id? | string | null | |
marginBottom? | oneOf(['space0']) | Currently we only allow space0 to remove bottom margin | null |
variant | headingVariants | 'heading10', 'heading20', 'heading30', 'heading40', 'heading50', 'heading60' | null |
display? | CSS display property options | 'block', 'inline', 'inline-block', 'flex', 'inline-flex', 'grid', 'inline-grid', and more | "block" |
element? | string | Overrides the default element name to apply unique styles with the Customization Provider | 'HEADING' |
Changelog
733709127
#3395 Thanks @SiTaggart! - Modified the compile target of our JavaScript bundles fromnode
tobrowser
to minimize the risk of clashing with RequireJS. This is marked as a major out of an abundance of caution. You shouldn't need to do anything but we wanted you to be aware of the change on the off chance it has unintended consequences
- Updated dependencies [
733709127
]:- @twilio-paste/color-contrast-utils@5.0.0
- @twilio-paste/text@10.0.0
- @twilio-paste/customization@8.0.0
- @twilio-paste/design-tokens@10.0.0
- @twilio-paste/animation-library@2.0.0
- @twilio-paste/styling-library@3.0.0
- @twilio-paste/style-props@9.0.0
- @twilio-paste/theme@11.0.0
- @twilio-paste/types@6.0.0
4d1f7c65e
#3360 Thanks @SiTaggart! - Improved types where Paste extends the base HTML element that a component is based on, so that the existing blocked styling properties are not exposed as valid properties for the component via Typescript. This leads to less confusion around what is supported by a Paste component.Existing blocked component properties include:
className
style
color
3ab2bb6f4
#3114 Thanks @SiTaggart! - ### Breaking changeWe have moved
@types/react
and@types/react-dom
to peer dependencies of the library. This should allow for greater control and backwards compatibility with older versions of React as Paste is no longer bundling the type libraries.Your application likely has both of these as dependencies anyway, but it is now up to you to manage that version number.
Action needed
Ensure
@types/react
and@types/react-dom
are installed as dependencies of your application.
- Updated dependencies [
bce889344
,3ab2bb6f4
,3ab2bb6f4
]:- @twilio-paste/theme@10.0.0
- @twilio-paste/text@9.0.0
- @twilio-paste/customization@7.0.0
- @twilio-paste/style-props@8.0.0
- @twilio-paste/types@5.0.0
d97098846
#3020 Thanks @SiTaggart! - This major version included listing all the missing peer dependencies for each Paste package.If you are using a package from Paste in isolation from Core, when upgrading to this latest version, be sure to correctly install all the missing peer dependencies.
154b02c06
#3010 Thanks @shleewhite! - [Heading] Update styles to align with new Paste Twilio themeUpdated dependencies [
dbd9bf992
,3c89fd83d
,d97098846
,0acdf3486
,ef094db4a
,0acdf3486
]:- @twilio-paste/design-tokens@9.0.0
- @twilio-paste/text@8.0.0
- @twilio-paste/customization@6.0.0
- @twilio-paste/animation-library@1.0.0
- @twilio-paste/styling-library@2.0.0
- @twilio-paste/style-props@7.0.0
- @twilio-paste/theme@9.0.0
- @twilio-paste/types@4.0.0
- @twilio-paste/color-contrast-utils@4.0.0
a4c9e70b0
#2763 Thanks @shleewhite! - Update ESLint rules, which changed some formatting.
- Updated dependencies [
12c4ba22a
,364083627
,364083627
,364083627
,364083627
]:- @twilio-paste/style-props@6.0.0
- @twilio-paste/design-tokens@8.0.0
- @twilio-paste/theme@8.0.0
- @twilio-paste/text@7.0.0
ae9dd50f
#2466 Thanks @TheSisb! - [All packages] Update our ESBuild version and remove minification of identifiers in our production builds.
- Updated dependencies [
09762f0f
,09762f0f1
,09762f0f1
]:- @twilio-paste/text@6.0.0
- @twilio-paste/styling-library@1.0.0
- @twilio-paste/theme@7.0.0
- @twilio-paste/style-props@5.0.0
73c596919
#2269 Thanks @SiTaggart! - Fixed a regression with the compilation script that caused incompatible ESM module importing of JSON files.
c867e3f48
#2237 Thanks @SiTaggart! - Updated a build dependency (esbuild) which changes the output of our builds slightly, without materially changing anything about the code.
- Updated dependencies [
0a52eeee
,0a52eeee
,04de0d1d
,04de0d1d
,04de0d1d
]:- @twilio-paste/design-tokens@7.0.0
- @twilio-paste/theme@6.0.0
- @twilio-paste/style-props@4.0.0
- @twilio-paste/text@5.0.0
ab0b98bc
#2088 Thanks @gloriliale! - [Heading] Added the prop "display" to Heading to make aligning Headings with Icons possible
b7675915
#1985 Thanks @TheSisb! - For debugging purposes we now ship afilename.debug.js
unminified version of each component or library in Paste.
ed5c0a49c
#1965 Thanks @shleewhite! - Upgrade Paste to use React 17 by default, but maintain React 16 support for consumers.
2d61c95d
#1766 Thanks @richbachman! - [Heading] Enable Heading to respect element customizations set on the customization provider. Heading now enables setting an element name on the underlying HTML element and checks the emotion theme object to determine whether it should merge in custom styles to the ones set by the component author.
0eded1fd
#1319 Thanks @SiTaggart! - Change internal dependencies to have minor range matching on version numbers
- Updated dependencies [
514bd5aa
]:- @twilio-paste/theme@5.0.1
- @twilio-paste/text@4.0.1
- @twilio-paste/style-props@3.0.1
- Updated dependencies [
4c9ed5ca
,26c828d8
]:- @twilio-paste/design-tokens@6.6.0
- @twilio-paste/theme@5.0.0
- @twilio-paste/text@4.0.0
- @twilio-paste/style-props@3.0.0
- Updated dependencies [
944c3407
]:- @twilio-paste/design-tokens@6.5.2
- @twilio-paste/text@3.0.1
- @twilio-paste/style-props@2.0.1
- @twilio-paste/theme@4.3.1
- Updated dependencies [
f1675586
]:- @twilio-paste/theme@4.3.0
- @twilio-paste/text@3.0.0
- @twilio-paste/style-props@2.0.0
a12acb61
#1158 Thanks @richbachman! - Pinned all twilio-paste package versions in order to keep them in sync with core when they are updated by changesets.Updated dependencies [
a12acb61
,a12acb61
,a12acb61
]:- @twilio-paste/theme@4.2.2
- @twilio-paste/style-props@1.9.2
- @twilio-paste/text@2.5.2
All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.
3.1.1 (2021-01-25)
Note: Version bump only for package @twilio-paste/heading
3.0.3 (2021-01-15)
Note: Version bump only for package @twilio-paste/heading
3.0.2 (2021-01-07)
Note: Version bump only for package @twilio-paste/heading
3.0.1 (2020-12-17)
Note: Version bump only for package @twilio-paste/heading
- heading: add forwardRef (c88d5a2)
- heading: component is now using fowardRef
2.1.6 (2020-12-15)
Note: Version bump only for package @twilio-paste/heading
2.1.5 (2020-12-11)
Note: Version bump only for package @twilio-paste/heading
2.1.4 (2020-12-11)
Note: Version bump only for package @twilio-paste/heading
2.1.3 (2020-12-09)
Note: Version bump only for package @twilio-paste/heading
2.1.2 (2020-12-02)
Note: Version bump only for package @twilio-paste/heading
2.1.1 (2020-11-11)
Note: Version bump only for package @twilio-paste/heading
2.0.50 (2020-11-06)
Note: Version bump only for package @twilio-paste/heading
2.0.49 (2020-11-05)
Note: Version bump only for package @twilio-paste/heading
2.0.48 (2020-10-23)
Note: Version bump only for package @twilio-paste/heading
2.0.47 (2020-10-15)
Note: Version bump only for package @twilio-paste/heading
2.0.46 (2020-10-13)
Note: Version bump only for package @twilio-paste/heading
2.0.45 (2020-10-07)
Note: Version bump only for package @twilio-paste/heading
2.0.44 (2020-10-07)
Note: Version bump only for package @twilio-paste/heading
2.0.43 (2020-10-07)
Note: Version bump only for package @twilio-paste/heading
2.0.42 (2020-10-07)
Note: Version bump only for package @twilio-paste/heading
2.0.41 (2020-09-22)
Note: Version bump only for package @twilio-paste/heading
2.0.40 (2020-09-21)
Note: Version bump only for package @twilio-paste/heading
2.0.39 (2020-09-15)
Note: Version bump only for package @twilio-paste/heading
2.0.38 (2020-09-15)
Note: Version bump only for package @twilio-paste/heading
2.0.37 (2020-09-08)
Note: Version bump only for package @twilio-paste/heading
2.0.36 (2020-09-08)
Note: Version bump only for package @twilio-paste/heading
2.0.35 (2020-09-03)
Note: Version bump only for package @twilio-paste/heading
2.0.34 (2020-08-31)
Note: Version bump only for package @twilio-paste/heading
2.0.33 (2020-08-31)
Note: Version bump only for package @twilio-paste/heading
2.0.32 (2020-08-31)
Note: Version bump only for package @twilio-paste/heading
2.0.31 (2020-08-24)
Note: Version bump only for package @twilio-paste/heading
2.0.30 (2020-08-19)
Note: Version bump only for package @twilio-paste/heading
2.0.29 (2020-08-12)
Note: Version bump only for package @twilio-paste/heading
2.0.28 (2020-08-12)
Note: Version bump only for package @twilio-paste/heading
2.0.27 (2020-08-06)
Note: Version bump only for package @twilio-paste/heading
2.0.26 (2020-08-04)
Note: Version bump only for package @twilio-paste/heading
2.0.25 (2020-08-04)
Note: Version bump only for package @twilio-paste/heading
2.0.24 (2020-07-30)
Note: Version bump only for package @twilio-paste/heading
2.0.23 (2020-07-29)
Note: Version bump only for package @twilio-paste/heading
2.0.22 (2020-07-22)
Note: Version bump only for package @twilio-paste/heading
2.0.21 (2020-07-15)
Note: Version bump only for package @twilio-paste/heading
2.0.20 (2020-07-14)
Note: Version bump only for package @twilio-paste/heading
2.0.19 (2020-07-14)
Note: Version bump only for package @twilio-paste/heading
2.0.18 (2020-07-01)
Note: Version bump only for package @twilio-paste/heading
2.0.17 (2020-07-01)
Note: Version bump only for package @twilio-paste/heading
2.0.16 (2020-06-29)
Note: Version bump only for package @twilio-paste/heading
2.0.15 (2020-06-25)
Note: Version bump only for package @twilio-paste/heading
2.0.14 (2020-06-22)
Note: Version bump only for package @twilio-paste/heading
2.0.13 (2020-06-18)
Note: Version bump only for package @twilio-paste/heading
2.0.12 (2020-06-16)
Note: Version bump only for package @twilio-paste/heading
2.0.11 (2020-06-12)
Note: Version bump only for package @twilio-paste/heading
2.0.10 (2020-06-10)
Note: Version bump only for package @twilio-paste/heading
2.0.9 (2020-06-05)
Note: Version bump only for package @twilio-paste/heading
2.0.8 (2020-06-01)
Note: Version bump only for package @twilio-paste/heading
2.0.7 (2020-06-01)
Note: Version bump only for package @twilio-paste/heading
2.0.6 (2020-05-20)
Note: Version bump only for package @twilio-paste/heading
2.0.5 (2020-05-07)
Note: Version bump only for package @twilio-paste/heading
2.0.4 (2020-05-07)
Note: Version bump only for package @twilio-paste/heading
2.0.3 (2020-05-04)
Note: Version bump only for package @twilio-paste/heading
2.0.2 (2020-05-01)
Note: Version bump only for package @twilio-paste/heading
2.0.1 (2020-04-25)
Note: Version bump only for package @twilio-paste/heading
- heading: set variant as required, remove default variant (966ea9f)
- heading:
variant
is now a required prop, and no longer has a default value.
1.3.1 (2020-04-22)
Note: Version bump only for package @twilio-paste/heading
- components: promote text components, spinner and primitive to prod (5605adc)
1.2.2 (2020-04-15)
Note: Version bump only for package @twilio-paste/heading
1.2.1 (2020-04-08)
- heading: package dependencies updated to be correct (6c20d9d)
- heading: allow for adding html attributes (b290a82)
1.1.13 (2020-04-07)
- heading: use color prop, update snapshots (2027f75)
1.1.12 (2020-04-02)
Note: Version bump only for package @twilio-paste/heading
1.1.11 (2020-03-24)
- heading: switch from theme-tokens to theme package dep (f12debc)
1.1.10 (2020-03-17)
Note: Version bump only for package @twilio-paste/heading
1.1.9 (2020-03-17)
Note: Version bump only for package @twilio-paste/heading
1.1.8 (2020-03-11)
Note: Version bump only for package @twilio-paste/heading
1.1.7 (2020-03-06)
Note: Version bump only for package @twilio-paste/heading
1.1.6 (2020-03-02)
Note: Version bump only for package @twilio-paste/heading
1.1.5 (2020-02-28)
Note: Version bump only for package @twilio-paste/heading
1.1.4 (2020-02-26)
Note: Version bump only for package @twilio-paste/heading
1.1.3 (2020-02-26)
1.1.2 (2020-02-18)
- heading: accept "header" an an "asTag" (eca2a1c)
1.1.1 (2020-02-14)
- heading: add missing peer deps (a26c926)
- heading: allow removing bottom margin (899e065)
1.0.14 (2020-02-13)
Note: Version bump only for package @twilio-paste/heading
1.0.13 (2020-02-11)
Note: Version bump only for package @twilio-paste/heading
1.0.12 (2020-02-11)
Note: Version bump only for package @twilio-paste/heading
1.0.11 (2020-02-11)
Note: Version bump only for package @twilio-paste/heading
1.0.10 (2020-02-03)
Note: Version bump only for package @twilio-paste/heading
1.0.9 (2020-01-24)
Note: Version bump only for package @twilio-paste/heading
1.0.8 (2020-01-17)
Note: Version bump only for package @twilio-paste/heading
1.0.7 (2019-12-20)
Note: Version bump only for package @twilio-paste/heading
1.0.6 (2019-12-19)
Note: Version bump only for package @twilio-paste/heading
1.0.5 (2019-12-05)
Note: Version bump only for package @twilio-paste/heading
1.0.4 (2019-11-21)
1.0.3 (2019-11-20)
1.0.2 (2019-11-18)
Note: Version bump only for package @twilio-paste/heading
1.0.1 (2019-11-12)
Note: Version bump only for package @twilio-paste/heading
- icons: delete old icons, add new streamline icons (#129) (571791d)
- typography: heading component (#149) (4e033e6)
- enable theme switching on the docsite (#124) (df797e5)
0.4.1 (2019-10-31)
Note: Version bump only for package @twilio-paste/heading
0.3.4 (2019-09-16)
Note: Version bump only for package @twilio-paste/heading
- change @paste scope to @twilio-paste (#2) (1d8d2ff)