Typography

Storybook
GitHub

Usage

This package provides <Body>, <Title>, <Legal> and <Type> components for rendering text using the five size type scale defined in base-styles.

import { Title, Body } from '@nerdwallet/react-typography';
<Title size="large">Title</Title>
<Body>Normal body text would be rendered here...</Body>

The <Title>, <Body>, and <Legal> components are abstractions that build on the underlying typographic scale. <Type> is a lower level component that gives raw access to the typographic scale and all styling options. The higher level <Title>, <Body>, and <Legal> components are encouraged to be the first choice for Nerds to use, before the atomic <Type /> component.

See the NDS Type Guidelines to learn more.

Loading examples...

<Body>

bold

boolean

Bold styling.

Default

false

children

node

Required

The content that the Type component will compose.


component

any

Use a custom component instead of the default <p> component.

Default

null

inline

boolean

By default <Type> is block-level (renders a <p> tag). If the inline prop is used, <Type> is inline (renders a <span> tag).

Default

false

italic

boolean

Italic styling.

Default

false

light

boolean

Sets text to "neutral-darker" defined in base-styles.

Default

false

size

"large" | "medium" | "small"

The suitable sizes for the TitleText. See the Type Guidelines for details.

Default

'medium'

<Heading>

children

node

Default

null

level

number | string

Set the heading level. Also determines what component to use by default (h1-h5).

Default

1

size

number | string

Font size, 1=smallest, 5=biggest. Derived from level if not specified.

Default

null

gotham

boolean

Use Gotham font. Font is inherited if not specified.

Default

false

chronicle

boolean

Use Chronicle font. Font is inherited if not specified.

Default

false

bold

boolean

Bold styling.

Default

true

italic

boolean

Italic styling.

Default

false

uppercase

boolean

Turn text uppercase and spaces out letters.

Default

false

light

boolean

Set text to a light gray color. Specifically "neutral-darker" defined in base-styles.

Default

false

color

string

Set text to a color defined by base-styles (overrides light).

Default

null

component

any

Use a custom component instead of the default h1-h5 html components.

Default

null

className

string

Default

null

semanticLevel

number

This is deprecated and here for backwards-compatibility. Use the `component` prop stead. Sets the heading semantic level and determines what h1-h5 element to use (separately from the visual style).

@deprecated

Default

null

<Title>

The <Title> abstraction on <Type> provides more clarity about when to use what style by providing syntax convenience and guardrails to stay within the guidelines.

It provides props to control the following:

  • size (T-Shirt scale of "x-large", "large", "medium", "small", and "x-small")
  • light to lighten the text color (to neutral-darker) to deemphasize the text
  • Other formatting (italic and inline)
  • Component (defaults to h1-h6 based on size)
<Title size="x-large">The largest title!</Title>

<Body>

The <Body> abstraction on <Type> provides more clarity about when to use what style by providing syntax convenience and guardrails to stay within the guidelines.

It provides props to control the following:

  • size (T-Shirt scale "large", "medium" and "small")
  • light to lighten the text color (to neutral-darker) to deemphasize the text
  • Other formatting (bold, italic, and inline)
<Body size="large">Large body text.</Body>
<Body size="medium">Medium (default) body text.</Body>
<Body size="small">Small body text.</Body>

<Legal>

The <Legal> abstraction on <Type> provides more clarity about when to use what style by providing syntax convenience and guardrails to stay within the guidelines. It doesn't impose any strict requirements on the semantics of the text; not all "legal text" will use this style and not all text using this style will be "legal text" and that's ok.

<Legal>Disclaimer and legal text.</Legal>

<Type>

The <Type> component is a flexible, low-level component for rendering text. It should generally be avoided in favor of <Body>, <Title>, or <Legal> but serves as an alternative if needed.

It provides props to control the following:

  • Size (0–5 scale)
  • Font family (Gotham or Chronicle)
  • Other formatting (bold, italic, uppercase)
<Type size="3">This is big "lead" text.</Type>
<Type size="2" chronicle bold>This is a bold line using Chronicle.</Type>
<Type size="4" component="div">This is bigger text in a div.</Type>

Size

There are five font sizes available on a geometric scale. There are technically two scales, one for mobile sized viewports and one for desktop sized viewports. Font sizes are "fluid" and will scale between the desktop and mobile sizes depending on the exact viewport.

As a general guideline, size 2 is considered "normal" or "body" text, size 1 is for "fine print", and size 3 can be used for lead text.

<Type size="1">Size 1 (smallest)</Type>
<Type size="2">Size 2 ("normal")</Type>
<Type size="3">Size 3</Type>
<Type size="4">Size 4</Type>
<Type size="5">Size 5 (biggest)</Type>

Font Family

The default font family is Gotham. Use the chronicle prop to use Chronicle. Gotham and Chronicle can both be used at all five sizes.

Formatting

The following props are provided for text formatting:

  • bold
  • italic
  • uppercase
<Type size="3">Bold <Type inline bold>text</Type> here</Type>

Color

light sets a neutral shade (neutral-darker) that has high enough contrast for accessibility.

In general this and the default color (neutral-darkest, black) are the only colors that should be used for readable text on white background.

This is discouraged, but if needed text color can be controlled using the color prop:

<Type color="red">Some red text</Type>

Custom Components

You can use the component prop to render a custom component (e.g,. div) instead of the default <p>. Some common use cases are:

  • h2 with size=4 and bold:

    <Type size="4" bold component="h2">My title goes here</Type>
  • div that looks the same as above:

    <Type size="4" bold component="div">My title goes here</Type>
  • h2 that looks like "normal" paragraph text:

    <Type size="2" component="h2">h2 that looks like default text</Type>

v8.1.0 Type Sizes Update

This component was updated on 4/6/2018 (v8.1.0) to use the new type scale in base-styles v2.16.0. The new type scale reduces the total number of font sizes from seven to five. For this reason, two heading levels that were previously two different font sizes, may now be the same font size. See the below diagram for how previous type sizes map to the new type scale:

Mapping of old type sizes to new type scale

This affects the <Heading> component, where level="2" and level="3" now provide the same size. You can use the size prop for more precise control over the heading's size.

Props

level Prop

The level prop controls the size of the heading and which html element is rendered.

  • If the size prop is provided, it will determine the text size over level.
  • If the component prop is provided, it will determine the rendered element over level.
// Render a <h1>
<Heading level="1">Hello</Heading>
// Render a <h1> with size 3 (same as <Type size="3" bold component="h1">)
<Heading size="3" level="1">Hello</Heading>

CSS Rules and Font Definitions

Warning: It's not safe to declare font-family anywhere in your local CSS. It's possible in the future we have different fonts depending on a class on the body for optimized loading. If you update font attributes manually, don't include the font family.

Note: Prior to 10/19/17, Gotham weights and styles were split between "Gotham Body" and "Gotham Display". In addition, every weight was available. Legacy code declarations of "GothamBody" or "GothamDisplay" fall back to an appropriate font.

Maintainers

This component is maintained by the FEI team.

See Also