Skip to content
Styled Typography
Docs
Installation

To download styled-typography run the following from within your project:

npm install styled-typography
Configuring the theme

You can customize styled-typography as much or as little as you’d like. A default will be provided that looks nice, visually.

The minimum to get started is to have a ThemeProvider somewhere near the top of your react tree. You don’t need to provide a theme if you want the default configuration.

import React from "react";
import { ThemeProvider } from "styled-components";

export const App = ({ children }) => (
	<ThemeProvider theme={{}}>{children}</ThemeProvider>
);

To configure the typographic setup, you can pass any and all configuration options listed below.

import React from "react";
import { ThemeProvider } from "styled-components";

// only customizes these three options. The rest will come from the default implementation
const typographyTheme = {
	fontSizes: ["2.369rem", "1.777rem", "1.333rem", "1rem", "0.75rem", "10px"],
	bodyFontFamily: "Source Code Pro, Input, monospace",
	headingFontFamily: "SF Display, Helvetica Neue, Circular, sans-serif"
};

export const App = ({ children }) => (
	<ThemeProvider theme={{ typography: typographyTheme }}>
		{children}
	</ThemeProvider>
);
Components

styled-typography provides give components for you to use and extend if needed: GlobalTypeStyles, Text, Heading, Span, and Link.

GlobalTypeStyles

The GlobalStyleStyles component is a way to quickly get global type styles into your app. This is useful if you intent to use Span or Link outside of Text/Heading, or other non-styled-typography components in your app. It’s important, however, that you place it within the ThemeProvider component.

import React from "react";
import { ThemeProvider } from "styled-components";
import { GlobalTypeStyles } from "styled-typography";

export const App = ({ children }) => (
	<ThemeProvider theme={{}}>
		<GlobalTypeStyles />
		{children}
	</ThemeProvider>
);
Text

The Text component resolves, by default, to a p component within the DOM. It accepts all props passable to p, as well as TextProps.

import React from "react";
import { Text, FontWeight, FontStyle } from "styled-typography";

export const HelloWorld = ({ className }) => (
	<Text
		className={className}
		level={4}
		fontWeight={FontWeight.Bold}
		fontStyle={FontStyle.Normal}
		color="red"
		lineHeight={1.3}
	>
		Hello, World!
	</Text>
);
Heading

The Heading component resolves, by default, to a div component within the DOM. It accepts all props passable to div, as well as TextProps.

But wait, you say! That’s not accessible! I know. By default, a div is not semantically an h1 element. ARIA, however, provides attributes that can make it a semantic header. Thus, the Header component automatically gets role="heading" and aria-level="#" attributes.

import React from "react";
import { Heading, FontWeight, FontStyle } from "styled-typography";

export const HelloWorld = ({ className }) => (
	<Heading
		className={className}
		level={1} // semantic level
		displayLevel={2} // display/visual level
		fontWeight={FontWeight.Bold}
		fontStyle={FontStyle.Normal}
		color="red"
		lineHeight={1}
	>
		Hello, World!
	</Heading>
);
Span

The Span component resolves, by default, to a span component within the DOM. It accepts all props passable to span, as well as TextProps.

import React from "react";
import { Span, FontWeight, FontStyle } from "styled-typography";

export const HelloWorld = ({ className }) => (
	<Span
		className={className}
		level={4}
		fontWeight={FontWeight.Bold}
		fontStyle={FontStyle.Normal}
		color="red"
		lineHeight={1.3}
	>
		Hello, World!
	</Span>
);

The Link component resolves, by default, to an a component within the DOM. It accepts all props passable to a, as well as TextProps.

import React from "react";
import { Link, FontWeight, FontStyle } from "styled-typography";

export const HelloWorld = ({ className }) => (
	<Link
		className={className}
		level={4}
		fontWeight={FontWeight.Bold}
		fontStyle={FontStyle.Normal}
		color="red"
		lineHeight={1.3}
		href="https://reactjs.org"
		target="_blank"
	>
		Hello, World!
	</Link>
);
Configuration options

Each of these options has what I consider to be a good default. You may override all of them, choose just a few to change, or do nothing.

fontSizes
Type: [string, string, string, string, string, string]
Default: ["2.369rem", "1.777rem", "1.333rem", "1rem", "0.750rem", "10px"]

fontSizes controls the 6 font size levels available to you. This generally corresponds to h1 through h6. 6 levels are required. If your app has less than that, just duplicate the smallest value until there are 6.

If only having 6 levels doesn’t work for you, please file an issue!

bodyFontFamily
Type: string
Default: "system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen', 'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue', sans-serif"

bodyFontFamily sets the font family for Text elements. Span and Link will inherit the global styles unless used within a Text or Heading element.

bodySize
Type: number
Default: 4

bodySize sets the default font size level for Text elements. Span and Link will inherit the global styles unless used within a Text or Heading element.

bodyWeight
Type: FontWeight
Default: FontWeight.Normal

bodyWeight sets the default font-weight for Text elements. Span and Link will inherit the global styles unless used within a Text or Heading element.

Available options are tied to the common name mapping system.

  • FontWeight.Hairline = "100"
  • FontWeight.ExtraLight = "200"
  • FontWeight.Light = "300"
  • FontWeight.Normal = "400"
  • FontWeight.Medium = "500"
  • FontWeight.SemiBold = "600"
  • FontWeight.Bold = "700"
  • FontWeight.ExtraBold = "800"
  • FontWeight.Heavy = "900"
  • FontWeight.Inherit = "inherit
bodyStyle
Type: FontStyle
Default: FontStyle.Regular

bodyStyle sets the default font-style for Text elements. Span and Link will inherit the global styles unless used within a Text or Heading element.

Available options are tied to the standard font-style options with an exception for oblique <angle>

  • FontStyle.Italic = "italic"
  • FontStyle.Oblique = "oblique"
  • FontStyle.Normal = "normal"
  • FontStyle.Inherit = "inherit
bodyColor
Type: string
Default: #000000

bodyColor sets the default color for Text elements. Span and Link will inherit the global styles unless used within a Text or Heading element.

bodyLineHeight
Type: string | number
Default: 1.4

bodyColor sets the default line-height for Text elements. Span and Link will inherit the global styles unless used within a Text or Heading element.

headingFontFamily
Type: string
Default: "system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen', 'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue', sans-serif"

headingFontFamily sets the font family for Heading elements. Span and Link will inherit the global styles unless used within a Text or Heading element.

headingSize
Type: number
Default: 4

headingSize sets the default font size level for Heading elements. Span and Link will inherit the global styles unless used within a Text or Heading element.

headingWeight
Type: FontWeight
Default: FontWeight.Normal

headingWeight sets the default font-weight for Heading elements. Span and Link will inherit the global styles unless used within a Text or Heading element.

Available options are tied to the common name mapping system.

  • FontWeight.Hairline = "100"
  • FontWeight.ExtraLight = "200"
  • FontWeight.Light = "300"
  • FontWeight.Normal = "400"
  • FontWeight.Medium = "500"
  • FontWeight.SemiBold = "600"
  • FontWeight.Bold = "700"
  • FontWeight.ExtraBold = "800"
  • FontWeight.Heavy = "900"
  • FontWeight.Inherit = "inherit
headingStyle
Type: FontStyle
Default: FontStyle.Regular

headingStyle sets the default font-style for Heading elements. Span and Link will inherit the global styles unless used within a Text or Heading element.

Available options are tied to the standard font-style options with an exception for oblique <angle>

  • FontStyle.Italic = "italic"
  • FontStyle.Oblique = "oblique"
  • FontStyle.Normal = "normal"
  • FontStyle.Inherit = "inherit
headingColor
Type: string
Default: #000000

headingColor sets the default color for Heading elements. Span and Link will inherit the global styles unless used within a Text or Heading element.

headingLineHeight
Type: string | number
Default: 1.4

headingColor sets the default line-height for Heading elements. Span and Link will inherit the global styles unless used within a Text or Heading element.

extra
Type: { text: string, heading: string, span: string, link: string }
Default: {}

extra injects extra styles for each type of component. Template strings and plain strings are acceptable values for each key.