A powerful toolkit for building websites with beautiful design.
- Install
- Demo/Playground
- Why?
- Themes & Plugins
- Sites That Use Typography.js
- JavaScript Usage
- Themes
- Plugins
- React.js Helper Components
- API
- Related
- Developing Typography.js
- Backers
- Sponsors
npm install typography
http://kyleamathews.github.io/typography.js
The goal of Typography.js is to provide a high-level, elegant API for expressing typographic design intent.
Typography is a complex system of interrelated styles. Hundreds of style declarations on dozens of elements must be in harmonious order. Effecting one design change can mean making dozens of tedious recalculations and CSS value changes. Creating new typography themes with CSS feels hard.
Typography.js provides a vastly simpler way to define and explore typography designs: just provide configuration to the Typography.js JavaScript API and it uses its Typography engine to generate CSS for block and inline elements.
Typography.js makes it easy to create designs that are unique, personal, and custom to your project.
- themes: Typography.js themes are simple Javascript objects. As such, they're easy to share across projects or even open source and share via NPM.
- plugins: Plugins are functions that extend or modify the core Typography engine. They can change how headers are styled or add specialized styles, e.g., for code or tables.
- bricolage.io (source)
- React Headroom (source)
- Gatsby Blog Starter (source)
- ollieglass.com
- Edit this file to add yours!
import Typography from 'typography'
const typography = new Typography({
baseFontSize: '18px',
baseLineHeight: 1.666,
headerFontFamily: ['Avenir Next', 'Helvetica Neue', 'Segoe UI', 'Helvetica', 'Arial', 'sans-serif'],
bodyFontFamily: ['Georgia', 'serif'],
// See below for the full list of options.
})
// Output CSS as string.
typography.toString()
// Or insert styles directly into the <head> (works well for client-only
// JS web apps)
typography.injectStyles()
We maintain 30 (and counting) themes that are ready to use on your next project. These are each published as separate NPM packages. Explore themes at http://kyleamathews.github.io/typography.js.
Here's an example of how to use the Funston theme.
- First, save the package to your project:
npm install --save typography-theme-funston
- Then import and pass into Typography.js when initializing
import Typography from 'typography'
import funstonTheme from 'typography-theme-funston'
const typography = new Typography(funstonTheme)
Themes are just JavaScript objects so it's easy to modify them as needed. For example, if you're using the Funston theme but want to increase the base font size slightly:
import Typography from 'typography'
import funstonTheme from 'typography-theme-funston'
funstonTheme.baseFontSize = '22px' // was 20px.
const typography = new Typography(funstonTheme)
Or you can use the imperative API overrideThemeStyles
to directly set/override styles on a theme:
import Typography from 'typography'
import funstonTheme from 'typography-theme-funston'
funston.overrideThemeStyles = ({ rhythm }, options) => ({
'h2,h3': {
marginBottom: rhythm(1/2),
marginTop: rhythm(2),
}
})
const typography = new Typography(funstonTheme)
- typography-theme-alton
- typography-theme-de-young
- typography-theme-doelger
- typography-theme-elk-glen
- typography-theme-fairy-gates
- typography-theme-funston
- typography-theme-grand-view
- typography-theme-irving
- typography-theme-judah
- typography-theme-lawton
- typography-theme-lincoln
- typography-theme-kirkham
- typography-theme-moraga
- typography-theme-noriega
- typography-theme-ocean-beach
- typography-theme-parnassus
- typography-theme-st-annes
- typography-theme-stow-lake
- typography-theme-sutro
- typography-theme-stern-grove
- typography-theme-twin-peaks
- typography-theme-wordpress-kubrick
- typography-theme-wordpress-2010
- typography-theme-wordpress-2011
- typography-theme-wordpress-2012
- typography-theme-wordpress-2013
- typography-theme-wordpress-2014
- typography-theme-wordpress-2015
- typography-theme-wordpress-2016
- typography-theme-wordpress-github
- typography-theme-wordpress-wikipedia
- If you publish your own, create a PR to add it here!
Plugins are functions that extend or modify the core typography engine.
They can change how headers are styled or add specialized styles, e.g., for
code or tables. Currently there's one plugin available,
typography-plugin-code
.
To use the Code plugin, first install using NPM:
npm install --save typography-plugin-code
Then add to your theme before creating a new Typography object:
import Typography from 'typography'
import CodePlugin from 'typography-plugin-code'
import sternGroveTheme from 'typography-theme-stern-grove'
sternGroveTheme.plugins = [
new CodePlugin(),
]
const typography = new Typography(sternGroveTheme)
Typography.js includes two helper components for your React.js projects:
TypographyStyle
and GoogleFont
. These are ideal for server-side
rendering.
TypographyStyle
creates a style element and inserts the generated CSS for
your theme. GoogleFont
creates the link element to include the Google
Fonts & weights specified in your theme.
Here's how to use:
- First, install the package:
npm install --save react-typography
- Then import them into your
html.js
file
import { TypographyStyle, GoogleFont } from 'react-typography'
// Best practice is to have a typography module
// where you define your theme.
import typography from 'utils/typography'
// Inside your React.js HTML component
<html>
<head>
<TypographyStyle typography={typography} />
<GoogleFont typography={typography} />
</head>
<body>
// stuff
</body>
</html>
When creating a new instance of Typography, you can pass in a configuration object. All configuration keys are optional.
- title: The theme title
- baseFontSize: The base font size in pixels, defaults to
16px
- baseLineHeight: The base line height using the css unitless number,
defaults to
1.5
- scaleRatio: The "scale ratio" for the theme. This value is the ratio
between the
h1
font size and thebaseFontSize
. So if the scale ratio is2
and thebaseFontSize
is16px
then theh1
font size is32px
.
{
scaleRatio: 2,
}
- googleFonts: An array specifying Google Fonts for this project.
googleFonts: [
{
name: 'Montserrat',
styles: [
'700',
],
},
{
name: 'Merriweather',
styles: [
'400',
'400i',
'700',
'700i',
],
},
],
- headerFontFamily: An array of strings specifying the font family
stack for headers, e.g.,
['Helvetica', 'sans-serif']
. Defaults to a system UI font stack. - bodyFontFamily: An array of strings specifying the font family stack
for the body, defaults to
['georgia', 'serif']
- headerColor: A CSS color string to be set on headers. Defaults to
inherit
. - bodyColor: A CSS color string to be set for body text. Defaults to
hsl(0,0%,0%,0.8)
. - headerWeight: Specifies the font weight for headers. Defaults to
bold
. - bodyWeight: Specifies the font weight for body text. Defaults to
normal
. - boldWeight: Specifies the font weight for "bold" (b, strong, dt, th)
elements. Defaults to
bold
. - blockMarginBottom: Specifies the default margin-bottom for block elements. Defaults to one "rhythm unit" (i.e. the height of the base line height).
- includeNormalize: Include normalize.css. Normalize.css is an
excellent project which works to normalize the base browser CSS across
browsers and serves as an excellent foundation for Typography.js. We
include normalize.css by default but if you're already including it
elsewhere in your project, you can disable including it here by passing
false
. - overrideStyles: Imperative API for directly adding to or overriding auto-generated styles. It's called with a Vertical Rhythm object, the options object, and the algorithmically generated styles.
overrideStyles: ({ adjustFontSizeTo, rhythm }, options, styles) => ({
h1: {
fontFamily: ['Montserrat', 'sans-serif'].join(','),
},
blockquote: {
...adjustFontSizeTo('19px'),
color: gray(41),
fontStyle: 'italic',
paddingLeft: rhythm(13/16),
marginLeft: rhythm(-1),
borderLeft: `${rhythm(3/16)} solid ${gray(10)}`,
},
'blockquote > :last-child': {
marginBottom: 0,
},
})
- overrideThemeStyles: This has the same function signature as
overrideStyles
but should be used in place ofoverrideStyles
when using a third party theme. This ensures you will not delete the theme's ownoverrideStyles
function.
overrideThemeStyles: ({ rhythm }, options, styles) => ({
'h2,h3': {
marginBottom: rhythm(1/2),
marginTop: rhythm(2),
}
})
Typography.js is a monorepo facilitated by Lerna.
TODO:
- Document constants
- Document compass-vertical-rhythm
- Document using Typgraphy.js for inline styles
Support us with a monthly donation and help us continue our activities. [Become a backer]
Become a sponsor and get your logo on our README on GitHub with a link to your site. [Become a sponsor]