React-Typography.js v0.15.0: A powerful toolkit for building websites with beautiful design

icon
Latest Release: v0.15.0

@BarryThePenguin did a fantastic job in #90 adding near 100% code coverage in one swoop. Thanks!

We also decided that the old body/header gray value & hue API was... confusing. That's not how most people think about the color of text. So now there's just bodyColor and headerColor. Also per @bvaughn suggestion in #92, headerColor defaults to 'inherit' so it's simpler to override header/body font colors together.

Source code(tar.gz)
Source code(zip)

Typography.js

A powerful toolkit for building websites with beautiful typography.

Typography.js Build Status Coverage Status

A powerful toolkit for building websites with beautiful design.

Install

npm install typography

Demo/playground

http://kyleamathews.github.io/typography.js

Why

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 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.

Sites that use Typography.js

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.

  1. First save the package to your project npm install --save typography-theme-funston
  2. 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

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 CSS for your theme.
  • GoogleFont creates the link element to include the Google Fonts & weights specified in your theme.

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>

Using with create-react-app

If you use the default create-react-app template, the above React.js solution will not work, and the typography.injectStyles() solution will not enable Google Fonts.. A workaround is to install typography-inject-fonts and do

import Typography from 'typography'
import funstonTheme from 'typography-theme-funston'
import injectFonts from 'typography-inject-fonts'

const typography = new Typography(funstonTheme)
typography.injectStyles()
injectFonts(typography)

API

Configuration

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.45.
  • scaleRatio: The "scale ratio" for the theme. This value is the ratio between the 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 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: 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) elements. Defaults to bold.
  • blockMarginBottom: Specify 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 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.

=======

Backers

Support us with a monthly donation and help us continue our activities. [Become a backer]

Sponsors

Become a sponsor and get your logo on our README on Github with a link to your site. [Become a sponsor]

Comments

  • Bump is-my-json-valid from 2.16.1 to 2.20.5
    Bump is-my-json-valid from 2.16.1 to 2.20.5

    May 8, 2021

    Bumps is-my-json-valid from 2.16.1 to 2.20.5.

    Commits
    Maintainer changes

    This version was pushed to npm by linusu, a new releaser for is-my-json-valid since your current version.


    Dependabot compatibility score

    Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.


    Dependabot commands and options

    You can trigger Dependabot actions by commenting on this PR:

    • @dependabot rebase will rebase this PR
    • @dependabot recreate will recreate this PR, overwriting any edits that have been made to it
    • @dependabot merge will merge this PR after your CI passes on it
    • @dependabot squash and merge will squash and merge this PR after your CI passes on it
    • @dependabot cancel merge will cancel a previously requested merge and block automerging
    • @dependabot reopen will reopen this PR if it is closed
    • @dependabot close will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually
    • @dependabot ignore this major version will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself)
    • @dependabot ignore this minor version will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself)
    • @dependabot ignore this dependency will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)
    • @dependabot use these labels will set the current labels as the default for future PRs for this repo and language
    • @dependabot use these reviewers will set the current reviewers as the default for future PRs for this repo and language
    • @dependabot use these assignees will set the current assignees as the default for future PRs for this repo and language
    • @dependabot use this milestone will set the current milestone as the default for future PRs for this repo and language

    You can disable automated security fix PRs for this repo from the Security Alerts page.

    dependencies 
    Reply
  • Bump hosted-git-info from 2.7.1 to 2.8.9
    Bump hosted-git-info from 2.7.1 to 2.8.9

    May 10, 2021

    Bumps hosted-git-info from 2.7.1 to 2.8.9.

    Changelog

    Sourced from hosted-git-info's changelog.

    2.8.9 (2021-04-07)

    Bug Fixes

    2.8.8 (2020-02-29)

    Bug Fixes

    • #61 & #65 addressing issues w/ url.URL implmentation which regressed node 6 support (5038b18), closes #66

    2.8.7 (2020-02-26)

    Bug Fixes

    • Do not attempt to use url.URL when unavailable (2d0bb66), closes #61 #62
    • Do not pass scp-style URLs to the WhatWG url.URL (f2cdfcf), closes #60

    2.8.6 (2020-02-25)

    2.8.5 (2019-10-07)

    Bug Fixes

    • updated pathmatch for gitlab (e8325b5), closes #51
    • updated pathmatch for gitlab (ffe056f)

    2.8.4 (2019-08-12)

    ... (truncated)

    Commits
    • 8d4b369 chore(release): 2.8.9
    • 29adfe5 fix: backport regex fix from #76
    • afeaefd chore(release): 2.8.8
    • 5038b18 fix: #61 & #65 addressing issues w/ url.URL implmentation which regressed nod...
    • 7440afa chore(release): 2.8.7
    • 2d0bb66 fix: Do not attempt to use url.URL when unavailable
    • f2cdfcf fix: Do not pass scp-style URLs to the WhatWG url.URL
    • e1b83df chore(release): 2.8.6
    • ff259a6 Ensure passwords in hosted Git URLs are correctly escaped
    • 624fd6f chore(release): 2.8.5
    • Additional commits viewable in compare view
    Maintainer changes

    This version was pushed to npm by nlf, a new releaser for hosted-git-info since your current version.


    Dependabot compatibility score

    Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.


    Dependabot commands and options

    You can trigger Dependabot actions by commenting on this PR:

    • @dependabot rebase will rebase this PR
    • @dependabot recreate will recreate this PR, overwriting any edits that have been made to it
    • @dependabot merge will merge this PR after your CI passes on it
    • @dependabot squash and merge will squash and merge this PR after your CI passes on it
    • @dependabot cancel merge will cancel a previously requested merge and block automerging
    • @dependabot reopen will reopen this PR if it is closed
    • @dependabot close will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually
    • @dependabot ignore this major version will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself)
    • @dependabot ignore this minor version will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself)
    • @dependabot ignore this dependency will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)
    • @dependabot use these labels will set the current labels as the default for future PRs for this repo and language
    • @dependabot use these reviewers will set the current reviewers as the default for future PRs for this repo and language
    • @dependabot use these assignees will set the current assignees as the default for future PRs for this repo and language
    • @dependabot use this milestone will set the current milestone as the default for future PRs for this repo and language

    You can disable automated security fix PRs for this repo from the Security Alerts page.

    dependencies 
    Reply
  • add new theme 'Vue'
    add new theme 'Vue'

    May 14, 2021

                                                                                                                                                                                                           
    Reply
  • Bump tar from 2.2.1 to 2.2.2
    Bump tar from 2.2.1 to 2.2.2

    Aug 4, 2021

    Bumps tar from 2.2.1 to 2.2.2.

    Commits
    • 523c5c7 2.2.2
    • 7ecef07 Bump fstream to fix hardlink overwriting vulnerability
    • 9fc84b9 Use {} for hardlink tracking instead of []
    • 15e59f1 Only track previously seen hardlinks
    • 4f85851 Ignore potentially unsafe files
    • See full diff in compare view

    Dependabot compatibility score

    Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.


    Dependabot commands and options

    You can trigger Dependabot actions by commenting on this PR:

    • @dependabot rebase will rebase this PR
    • @dependabot recreate will recreate this PR, overwriting any edits that have been made to it
    • @dependabot merge will merge this PR after your CI passes on it
    • @dependabot squash and merge will squash and merge this PR after your CI passes on it
    • @dependabot cancel merge will cancel a previously requested merge and block automerging
    • @dependabot reopen will reopen this PR if it is closed
    • @dependabot close will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually
    • @dependabot ignore this major version will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself)
    • @dependabot ignore this minor version will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself)
    • @dependabot ignore this dependency will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)
    • @dependabot use these labels will set the current labels as the default for future PRs for this repo and language
    • @dependabot use these reviewers will set the current reviewers as the default for future PRs for this repo and language
    • @dependabot use these assignees will set the current assignees as the default for future PRs for this repo and language
    • @dependabot use this milestone will set the current milestone as the default for future PRs for this repo and language

    You can disable automated security fix PRs for this repo from the Security Alerts page.

    dependencies 
    Reply
  • Bump path-parse from 1.0.5 to 1.0.7
    Bump path-parse from 1.0.5 to 1.0.7

    Aug 10, 2021

    Bumps path-parse from 1.0.5 to 1.0.7.

    Commits

    Dependabot compatibility score

    Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.


    Dependabot commands and options

    You can trigger Dependabot actions by commenting on this PR:

    • @dependabot rebase will rebase this PR
    • @dependabot recreate will recreate this PR, overwriting any edits that have been made to it
    • @dependabot merge will merge this PR after your CI passes on it
    • @dependabot squash and merge will squash and merge this PR after your CI passes on it
    • @dependabot cancel merge will cancel a previously requested merge and block automerging
    • @dependabot reopen will reopen this PR if it is closed
    • @dependabot close will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually
    • @dependabot ignore this major version will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself)
    • @dependabot ignore this minor version will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself)
    • @dependabot ignore this dependency will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)
    • @dependabot use these labels will set the current labels as the default for future PRs for this repo and language
    • @dependabot use these reviewers will set the current reviewers as the default for future PRs for this repo and language
    • @dependabot use these assignees will set the current assignees as the default for future PRs for this repo and language
    • @dependabot use this milestone will set the current milestone as the default for future PRs for this repo and language

    You can disable automated security fix PRs for this repo from the Security Alerts page.

    dependencies 
    Reply
  • Bump tmpl from 1.0.4 to 1.0.5
    Bump tmpl from 1.0.4 to 1.0.5

    Sep 21, 2021

    Bumps tmpl from 1.0.4 to 1.0.5.

    Commits

    Dependabot compatibility score

    Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.


    Dependabot commands and options

    You can trigger Dependabot actions by commenting on this PR:

    • @dependabot rebase will rebase this PR
    • @dependabot recreate will recreate this PR, overwriting any edits that have been made to it
    • @dependabot merge will merge this PR after your CI passes on it
    • @dependabot squash and merge will squash and merge this PR after your CI passes on it
    • @dependabot cancel merge will cancel a previously requested merge and block automerging
    • @dependabot reopen will reopen this PR if it is closed
    • @dependabot close will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually
    • @dependabot ignore this major version will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself)
    • @dependabot ignore this minor version will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself)
    • @dependabot ignore this dependency will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)
    • @dependabot use these labels will set the current labels as the default for future PRs for this repo and language
    • @dependabot use these reviewers will set the current reviewers as the default for future PRs for this repo and language
    • @dependabot use these assignees will set the current assignees as the default for future PRs for this repo and language
    • @dependabot use this milestone will set the current milestone as the default for future PRs for this repo and language

    You can disable automated security fix PRs for this repo from the Security Alerts page.

    dependencies 
    Reply
  • Fairy Gates Theme: Messed up text shadow in default starter project header
    Fairy Gates Theme: Messed up text shadow in default starter project header

    Mar 8, 2018

    This image shows what I see just following along with the tutorial (except I tried to use the fairy-gates theme instead of just lawton and bootstrap like the tutorial suggests). I don't see any issues with lawton or bootstrap.

    screen shot 2018-03-07 at 11 03 25 pm
    Reply
  • Javascript version
    Javascript version

    Mar 12, 2015

    Is there a way to get a dist (transpiled) version as plain Javascript? I don't use npm, or coffeescript in my project but would love to try this component?

    Reply
  • Add Breakpoints support
    Add Breakpoints support

    Mar 11, 2018

    Hey Kyle! I really wanted breakpoint support so I added it. Afterwards I realized I forgot to disable prettier so it added a lot of small changes to the formatting of your code which I'll fix first if you're interested in merging this. The purpose of this pull request is to see if you're good with the way I've implemented breakpoints. If you have any feedback I can modify the code however you'd like. I think the code could be made a little more DRY and overrides could be turned into a function so it can be called inside breakpoints as well instead of at the end. I also added breakpoint support in the spot where you indicated it should be.

    I wrapped the code that generates styles inside a function and then immediately called that and passed in the vertical rythm. I then also called that function for each breakpoint with a new vertical rythm for each breakpoint. New typography objects are being created for each breakpoint. Wherever the breakpoint isn't overriding the original object it will inherit from the original typography object. Afterwards the object is compared to the original object and only new declarations which aren't in the original object are being passed through. Finally the breakpoint objects are added onto the end of the original typography object in order. It works with toJSON and toString.

    Let me know what you think! Hopefully this is in the direction of how you were going to implement it.

    Reply
  • can include a CSS reset?
    can include a CSS reset?

    Jul 28, 2018

    does the module contain options to include a CSS reset? I tried to include a styles reset with a reset.css file but the file affects the settings when typography.js is enabled. Can't find a way to include a reset and not affecting my typography settings. Is there a way to get around this?

    Reply
  • Allow setting weight for body
    Allow setting weight for body

    Mar 26, 2015

    Would be nice to be able to set body font-weight independently of headings. For example, Roboto 400 is quite heavy for a body font

    Reply
  • Line height gets set in em instead of unitless
    Line height gets set in em instead of unitless

    Jan 19, 2018

    According to the docs,

    baseLineHeight: The base line height using the css unitless number, defaults to 1.5.

    However, line-height gets set in em units.

    typography js 2018-01-19 20-17-20
    Reply