Heading
A heading is a typography component used to display text in different sizes and formats.Migrating to new Heading API
As part of our new typography system, we've updated Heading to provide an API more consistent with
other Design System components. The primary change is replacing the level prop with size and
updating the values to reference t-shirt sizes.
New size
xxlarge (replaces h900)
xlarge (replaces h800)
large (replaces h700)
medium (replaces h600)
small (replaces h500)
xsmall (replaces h400)
xxsmall (replaces h300, h200, and h100)
import React, { Fragment } from 'react';
import Heading from '@atlaskit/heading/heading';
import { Stack } from '@atlaskit/primitives/compiled';
export default (): React.JSX.Element => {
return (
<Fragment>
{/* eslint-disable-next-line @atlaskit/ui-styling-standard/no-global-styles -- Ignored via go/DSP-18766 */}
<style>{`:root { --ds-font-family-heading: sans-serif; }`}</style>
<Stack space="space.100">
<Heading size="xsmall">New size</Heading>
<Heading size="xxlarge">xxlarge (replaces h900)</Heading>
<Heading size="xlarge">xlarge (replaces h800)</Heading>
<Heading size="large">large (replaces h700)</Heading>
<Heading size="medium">medium (replaces h600)</Heading>
<Heading size="small">small (replaces h500)</Heading>
<Heading size="xsmall">xsmall (replaces h400)</Heading>
<Heading size="xxsmall">xxsmall (replaces h300, h200, and h100)</Heading>
</Stack>
</Fragment>
);
};level renamed to size
The level prop on the Heading component has been renamed to size to better reflect its
purpose. The level prop is still supported but is deprecated and will be removed in a future major
release.
To migrate from level to size, rename the prop in your code and update the value to match the
new size values referenced in the example above.
- <Heading level="h300">
+ <Heading size="xxsmall">This migration isn't 1:1 as the size prop has a different set of values to the level prop,
although equivalents exist for most levels.
Certain headings (h100, h300) have no direct equivalents in the new typography system. For these,
assess whether the text should still be a heading and if so, use the xxsmall size.
The removal of the all caps style from h300 and lighter colors from h100 and h200 is intentional for accessibility reasons.
Other props on the Heading component have not changed.