Heading

heading text structured in levels

Storybook

CodeSandbox

Github

Using Grommet for HPE?See Heading examples and guidance.

Props

a11yTitle

Custom label to be used by screen readers. When provided, an aria-label will be added to the element.

string

"a user friendly label for screen readers"

alignSelf

How to align along the cross axis when contained in a Box or along the column axis when contained in a Grid.

string

"start"

"center"

"end"

"stretch"

"baseline"

color

A color identifier to use for the text color.

string

A hex, name, or rgb value.

"brand"

object

An object with a color for dark and light modes.

{ dark: "string", light: "string" }

fill

Whether the width should fill the container.

boolean

true

false

gridArea

The name of the area to place this inside a parent Grid.

string

"a parent grid area name"

level

The heading level. It corresponds to the number after the 'H' for the DOM tag. Set the level for semantic accuracy and accessibility. The sizing can be further adjusted using the size property.

string

"1"

"2"

"3"

"4"

"5"

"6"

number

margin

The amount of margin around the component.

string

"none"

"xxsmall"

"xsmall"

"small"

"medium"

"large"

"xlarge"

object

Can be specified to distinguish horizontal margin, vertical margin, and margin on a particular side.

{
    vertical: "...",
    horizontal: "...",
    top: "...",
    bottom: "...",
    left: "...",
    right: "..."
}

overflowWrap

Specifies whether line breaks should be inserted within an otherwise unbreakable string, such as long word or URL, to prevent text from overflowing its container.

string

"normal" specifies that line breaks may only occur at normal string breakpoints, such as a space or hyphen.

"anywhere" and "break-word" both prevent text from overflowing by allowing strings to break at any point.

They differ in how their min-content widths are calculated, affecting how they are treated in flex layouts such a Box and Grid. "anywhere" is the most flexible, its min-content width is equal to width longest word in the string. "break-word" prefers to occupy the intrinsic width of the string.

"normal"

"anywhere"

"break-word"

responsive

Whether the font size should be scaled for mobile environments.

boolean

true

false

size

The font size is primarily driven by the chosen tag. But, it can be adjusted via this size property. The tag should be set for semantic correctness and accessibility. This size property allows for stylistic adjustments.

string

"small"

"medium"

"large"

"xlarge"

"string"

textAlign

How to align the text inside the heading.

string

"start"

"center"

"end"

"justify"

truncate

Restrict the text to a single line and truncate with ellipsis if it is too long to all fit.

boolean

true

false

weight

Font weight

string

"normal"

"bold"

"lighter"

"bolder"

number

React/DOM Properties

At its core, the Heading component is a regular <h1> element. Thus, both DOM and React properties, methods, and events are accessible. To read up on all of the possible DOM attributes and types available for h1 elements, check out this MDN Web Documents page. To learn more about DOM events and methods, you can read more on the MDN Web Events documentation page.

At its core, the Heading component is a regular <h2> element. Thus, both DOM and React properties, methods, and events are accessible. To read up on all of the possible DOM attributes and types available for h2 elements, check out this MDN Web Documents page. To learn more about DOM events and methods, you can read more on the MDN Web Events documentation page.

At its core, the Heading component is a regular <h3> element. Thus, both DOM and React properties, methods, and events are accessible. To read up on all of the possible DOM attributes and types available for h3 elements, check out this MDN Web Documents page. To learn more about DOM events and methods, you can read more on the MDN Web Events documentation page.

At its core, the Heading component is a regular <h4> element. Thus, both DOM and React properties, methods, and events are accessible. To read up on all of the possible DOM attributes and types available for h4 elements, check out this MDN Web Documents page. To learn more about DOM events and methods, you can read more on the MDN Web Events documentation page.

Also, feel free to read about the types of React events available, or see how DOM attributes change in React. Working in tandem with Styled Components, you also have access to the as property.

Theme

global.breakpoints

The possible breakpoints that could affect font-size and max-width

object

{
  small: {
    value: 768,
    borderSize: {
      xsmall: "1px",
      small: "2px",
      medium: "4px",
      large: "6px",
      xlarge: "12px"
    },
    edgeSize: {
      none: "0px",
      hair: "1px",
      xxsmall: "2px",
      xsmall: "3px",
      small: "6px",
      medium: "12px",
      large: "24px",
      xlarge: "48px"
    },
    size: {
      xxsmall: "24px",
      xsmall: "48px",
      small: "96px",
      medium: "192px",
      large: "384px",
      xlarge: "768px",
      full: "100%"
    }
  },
  medium: { value: 1536 },
  large: {}
}

global.edgeSize

The possible sizes for margin.

object

    {
      none: '0px',
      hair: '1px',
      xxsmall: '3px',
      xsmall: '6px',
      small: '12px',
      medium: '24px',
      large: '48px',
      xlarge: '96px',
      responsiveBreakpoint: 'small'
    }

heading.color

The color of the heading.

string

A hex, name, or rgb value.

"brand"

object

An object with a color for dark and light modes.

{ dark: "string", light: "string" }

heading.extend

Any additional style for Heading.

string

Any CSS.

css`color: 'blue'`

function

(props) => {}

heading.level

The level that impacts line-height, max-width, font size, weight and family of the Heading. Heading styling is automatically adjusted at different screen sizes. When the heading.responsiveBreakpoint is hit ("small" by default), all heading styles will automatically be adjusted. A heading of level 1, for example, will use the styling defined in heading level 2; a heading of level 2 will use the styling defined in heading level 3 and so forth. The tag in the DOM is not adjusted. A heading of level 1 remains an h1. The styling adjustment is intended to aid readability on smaller screens but will not semantically affect your application structure. If you do not want this responsive styling to occur, you can set heading.responsiveBreakpoint to undefined.

object

{
  1: {
    font: {},
    small: {
      size: "34px",
      height: "40px",
      maxWidth: "816px"
    },
    medium: {
      size: "50px",
      height: "56px",
      maxWidth: "1200px"
    },
    large: {
      size: "82px",
      height: "88px",
      maxWidth: "1968px"
    },
    xlarge: {
      size: "114px",
      height: "120px",
      maxWidth: "2736px"
    }
  },
  2: {
    font: {},
    small: {
      size: "26px",
      height: "32px",
      maxWidth: "624px"
    },
    medium: {
      size: "34px",
      height: "40px",
      maxWidth: "816px"
    },
    large: {
      size: "50px",
      height: "56px",
      maxWidth: "1200px"
    },
    xlarge: {
      size: "66px",
      height: "72px",
      maxWidth: "1584px"
    }
  },
  3: {
    font: {},
    small: {
      size: "22px",
      height: "28px",
      maxWidth: "528px"
    },
    medium: {
      size: "26px",
      height: "32px",
      maxWidth: "624px"
    },
    large: {
      size: "34px",
      height: "40px",
      maxWidth: "816px"
    },
    xlarge: {
      size: "42px",
      height: "48px",
      maxWidth: "1008px"
    }
  },
  4: {
    font: {},
    small: {
      size: "18px",
      height: "24px",
      maxWidth: "432px"
    },
    medium: {
      size: "18px",
      height: "24px",
      maxWidth: "432px"
    },
    large: {
      size: "18px",
      height: "24px",
      maxWidth: "432px"
    },
    xlarge: {
      size: "18px",
      height: "24px",
      maxWidth: "432px"
    }
  },
  5: {
    font: {},
    small: {
      size: "16px",
      height: "22px",
      maxWidth: "384px"
    },
    medium: {
      size: "16px",
      height: "22px",
      maxWidth: "384px"
    },
    large: {
      size: "16px",
      height: "22px",
      maxWidth: "384px"
    },
    xlarge: {
      size: "16px",
      height: "22px",
      maxWidth: "384px"
    }
  },
  6: {
    font: {},
    small: {
      size: "14px",
      height: "20px",
      maxWidth: "336px"
    },
    medium: {
      size: "14px",
      height: "20px",
      maxWidth: "336px"
    },
    large: {
      size: "14px",
      height: "20px",
      maxWidth: "336px"
    },
    xlarge: {
      size: "14px",
      height: "20px",
      maxWidth: "336px"
    }
  }
}

heading.weight

Default heading weight used unless a per level heading is defined.

number

heading.font

Default heading font used unless a per level heading is defined.

object

{}

heading.skeleton

Any Skeleton properties which will be applied to the Heading when in skeleton mode. For the Heading to be in skeleton mode, use the 'skeleton' property on a parent Box.

object

{ width: { min: '200px' }}

heading.responsiveBreakpoint

The breakpoint to trigger changes in the Heading layout. The actual values will be derived from global.breakpoints.

string

"small"