Typography.js
A powerful toolkit for building websites with beautiful typography.A powerful toolkit for building websites with beautiful design.Install
npm install typography
Demo/playground
http://kyleamathews.github.io/typography.jsWhy
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. 100s of style declarations on dozens of elements must be in harmonious order. Trying 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.
You provide configuration to the Typography.js JS 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 & Plugins
- themes: Typography.js themes are simple Javascript objects. As
- plugins: Plugins are functions that extend or modify the core
Sites that use Typography.js
- bricolage.io (source)
- React Headroom (source)
- Gatsby Blog Starter (source)
- ollieglass.com
- Edit this file to add yours!
Javascript usage
import Typography from 'typography'
const typography = new Typography({
baseFontSize: '18px',
baseLineHeight: 1.45,
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()
Themes
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.Using themes
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 when initializing.
import Typography from 'typography'
import funstonTheme from 'typography-theme-funston'
const typography = new Typography(funstonTheme)
Customizing themes
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'
funstonTheme.overrideThemeStyles = ({ rhythm }, options) => ({
'h2,h3': {
marginBottom: rhythm(1/2),
marginTop: rhythm(2),
}
})
const typography = new Typography(funstonTheme)
Published Typography.js Themes
- 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
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)
React.js helper components.
Typography.js includes two helper components for your React.js projects,TypographyStyle
and GoogleFont
. These are ideal for
server-rendering.TypographyStyle
creates a style element and inserts the generated
GoogleFont
creates the link element to include the Google Fonts &
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>
API
Configuration
When creating a new instance of Typography, you can pass in an 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.45
. - scaleRatio: The "scale ratio" for the theme. This value is the ratio
h1
font size and the baseFontSize
. So if the scale ratio is 2
and the baseFontSize
is 16px
then the h1
font size is 32px
.
{
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
['Helvetica', 'sans-serif']
. Defaults to a
system UI font stack.- bodyFontFamily: An array of strings specifying the font family
['georgia', 'serif']
.- headerColor: A css color string to be set on headers. Defaults
inherit
.- bodyColor: A css color string to be set for body text. Defaults
hsl(0,0%,0%,0.8)
.- headerWeight: Specify the font weight for headers. Defaults to
bold
.- bodyWeight: Specify the font weight for body text. Defaults to
normal
.- boldWeight: Specify the font weight for "bold" (b, strong, dt, th)
bold
.- blockMarginBottom: Specify the default margin-bottom for block
- includeNormalize: Include normalize.css.
false
.- overrideStyles: Imperative API for directly adding to or
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 of overrideStyles
when
using a 3rd-party theme so as to not delete the theme's own
overrideStyles
function.overrideThemeStyles: ({ rhythm }, options, styles) => ({
'h2,h3': {
marginBottom: rhythm(1/2),
marginTop: rhythm(2),
}
})
Related
Developing Typography.js
Typography.js is a monorepo facilitated by Lerna.TODO: document constants + compass-vertical-rhythm + using typgraphy.js for inline styles.
=======