Component API

Heading

Basic Usage

The Heading component can be used with the level prop to render the HTML heading elements, levels 1-6.

import React from 'react';
import { Heading } from 'react-magma-dom';

export function Example() {
  return (
    <>
      <Heading level={1}>Heading 1</Heading>
      <Heading level={2}>Heading 2</Heading>
      <Heading level={3}>Heading 3</Heading>
      <Heading level={4}>Heading 4</Heading>
      <Heading level={5}>Heading 5</Heading>
      <Heading level={6}>Heading 6</Heading>
    </>
  );
}

Size

There are six visual styles for the heading: headingXLarge, headingLarge, headingMedium, headingSmall, headingXSmall and heading2XSmall. If not specified, a corresponding visual style will be applied based on the heading.

Visual style and heading level can be set independently so you can specify the correct semantic level and then apply any of the visual styles to change the visual appearance to fit your design.

Furthermore, the visualStyle prop can also accept the values for the four different paragraph visual styles: bodyLarge, bodyMedium, bodySmall, and bodyXSmall. These are sizes are also used with the Paragraph component.

import React from 'react';
import { Heading, TypographyVisualStyle } from 'react-magma-dom';

export function Example() {
  return (
    <>
      <Heading level={2} visualStyle={TypographyVisualStyle.headingXLarge}>
        H2 styled as Heading XLarge
      </Heading>
      <Heading level={2} visualStyle={TypographyVisualStyle.headingLarge}>
        H2 styled as Heading Large
      </Heading>
      <Heading level={2} visualStyle={TypographyVisualStyle.headingMedium}>
        H2 styled as Heading Medium
      </Heading>
      <Heading level={2} visualStyle={TypographyVisualStyle.headingSmall}>
        H2 styled as Heading Small
      </Heading>
      <Heading level={2} visualStyle={TypographyVisualStyle.headingXSmall}>
        H2 styled as Heading XSmall
      </Heading>
      <Heading level={2} visualStyle={TypographyVisualStyle.heading2XSmall}>
        H2 styled as Heading 2XSmall
      </Heading>

      <Heading level={2} visualStyle={TypographyVisualStyle.bodyLarge}>
        H2 styled as Body Large
      </Heading>
      <Heading level={2} visualStyle={TypographyVisualStyle.bodyMedium}>
        H2 styled as Body Medium
      </Heading>
      <Heading level={2} visualStyle={TypographyVisualStyle.bodySmall}>
        H2 styled as Body Small
      </Heading>
      <Heading level={2} visualStyle={TypographyVisualStyle.bodyXSmall}>
        H2 styled as Body XSmall
      </Heading>
    </>
  );
}

Context Variant

The contextVariant prop can be used to set additional styles on a heading component. The contextVariant can affect the font-size, text-transform, or font-family. The default contextVariant is default.

The expressive context variant can be used in marketing contexts, which may require more variety than the default styles.

The narrative context variant can be used for content-heavy contexts, such as a blog post or an e-reader.

import React from 'react';
import { Heading, TypographyContextVariant } from 'react-magma-dom';

export function Example() {
  return (
    <>
      <div style={{ marginBottom: '40px' }}>
        <Heading contextVariant={TypographyContextVariant.expressive} level={1}>
          Expressive Heading 1
        </Heading>
        <Heading contextVariant={TypographyContextVariant.expressive} level={2}>
          Expressive Heading 2
        </Heading>
        <Heading contextVariant={TypographyContextVariant.expressive} level={3}>
          Expressive Heading 3
        </Heading>
        <Heading contextVariant={TypographyContextVariant.expressive} level={4}>
          Expressive Heading 4
        </Heading>
        <Heading contextVariant={TypographyContextVariant.expressive} level={5}>
          Expressive Heading 5
        </Heading>
        <Heading contextVariant={TypographyContextVariant.expressive} level={6}>
          Expressive Heading 6
        </Heading>
      </div>
      <div>
        <Heading contextVariant={TypographyContextVariant.narrative} level={1}>
          Narrative Heading 1
        </Heading>
        <Heading contextVariant={TypographyContextVariant.narrative} level={2}>
          Narrative Heading 2
        </Heading>
        <Heading contextVariant={TypographyContextVariant.narrative} level={3}>
          Narrative Heading 3
        </Heading>
        <Heading contextVariant={TypographyContextVariant.narrative} level={4}>
          Narrative Heading 4
        </Heading>
        <Heading contextVariant={TypographyContextVariant.narrative} level={5}>
          Narrative Heading 5
        </Heading>
        <Heading contextVariant={TypographyContextVariant.narrative} level={6}>
          Narrative Heading 6
        </Heading>
      </div>
    </>
  );
}

Color

The color prop can be used to change the color of the heading to convey additional meaning. It accepts the values: success, danger and subdued.

import React from 'react';
import { Heading, TypographyColor } from 'react-magma-dom';

export function Example() {
  return (
    <>
      <Heading color={TypographyColor.success} level={2}>
        Success Color Heading
      </Heading>

      <Heading color={TypographyColor.danger} level={2}>
        Danger Color Heading
      </Heading>

      <Heading color={TypographyColor.subdued} level={2}>
        Subdued Color Heading
      </Heading>
    </>
  );
}

Inverse

The isInverse property is an optional boolean that changes the colors so the component can appear on a dark background.

import React from 'react';
import { Card, CardBody, Heading, TypographyColor } from 'react-magma-dom';

export function Example() {
  return (
    <Card isInverse>
      <CardBody>
        <Heading isInverse level={2}>
          Heading 2
        </Heading>

        <Heading color={TypographyColor.success} isInverse level={2}>
          Success Color Heading
        </Heading>

        <Heading color={TypographyColor.danger} isInverse level={2}>
          Danger Color Heading
        </Heading>

        <Heading isInverse level={2} color={TypographyColor.subdued}>
          Heading 2 Subdued
        </Heading>
      </CardBody>
    </Card>
  );
}

No Margins

By default, the Heading component includes margins on the top and bottom. When the noMargins prop is applied, the element will have a margin value of 0.

import React from 'react';
import { Heading } from 'react-magma-dom';

export function Example() {
  return (
    <>
      <Heading noMargins level={1}>
        Heading 1
      </Heading>
      <Heading noMargins level={2}>
        Heading 2
      </Heading>
      <Heading noMargins level={3}>
        Heading 3
      </Heading>
      <Heading noMargins level={4}>
        Heading 4
      </Heading>
      <Heading noMargins level={5}>
        Heading 5
      </Heading>
      <Heading noMargins level={6}>
        Heading 6
      </Heading>
    </>
  );
}

Forward Ref

Using React's forwardRef feature you can gain access to the reference of the internal heading.

import React from 'react';
import { Button, Heading } from 'react-magma-dom';

export function Example() {
  const headingRef = React.useRef<HTMLHeadingElement>();

  function handleClick() {
    headingRef.current.tabIndex = -1;
    headingRef.current.focus();
  }

  return (
    <>
      <Heading ref={headingRef} level={1}>
        Heading to Be Focused
      </Heading>

      <Button onClick={handleClick}>Click to focus heading</Button>
    </>
  );
}

Testing

Passing in the testId prop will add the data-testid attribute to the heading element for easier querying in tests.

<h1 data-testid="test-id">Heading 1</h1>

Heading Props

This component uses forwardRef. The ref is applied to the heading element.

All of the global HTML attributes can be provided as props and will be applied to the heading (h1-6) element that gets rendered.

= required prop

Property	Type	Default	Description
as	string	-
children	any	-	The content of the component
color	enum, one of: `TypographyColor.danger` `TypographyColor.default` `TypographyColor.subdued` `TypographyColor.success`	TypographyColor.default	The color of the component, that helps to convey meaning or relative emphasis
contextVariant	enum, one of: `TypographyContextVariant.default` `TypographyContextVariant.expressive` `TypographyContextVariant.narrative`	TypographyColor.default	Additional styles for typography based on the context of the content
element	string	-
isInverse	boolean	false	If true, the component will have inverse styling to better appear on a dark background
level Required	1 \| 2 \| 3 \| 4 \| 5 \| 6	-	Number to indicate which level heading will render (e.g. h1, h2 etc.)
noMargins	boolean	-
ref	any	-
testId	string	-	Test ID attached to an internal element as `data-testid` for consumer testing
theme	any	-
visualStyle	enum, one of: `TypographyVisualStyle.bodyLarge` `TypographyVisualStyle.bodyMedium` `TypographyVisualStyle.bodySmall` `TypographyVisualStyle.bodyXSmall` `TypographyVisualStyle.heading2XSmall` `TypographyVisualStyle.headingLarge` `TypographyVisualStyle.headingMedium` `TypographyVisualStyle.headingSmall` `TypographyVisualStyle.headingXLarge` `TypographyVisualStyle.headingXSmall`	-	Applies visual styles including font-size, font-weight, line-height and margins