react-with-async-fonts

React module for working with async loaded custom web fonts, based on fontfaceobserver.

Note: version 4.x introduces breaking changes with new API. It addresses bunch of issues, including canceling promises, better performance, and TS typings.

Quick Start
API
Examples
License

Quick Start

Install react-with-async-fonts:

npm:

npm install --save react-with-async-fonts

yarn:

yarn add react-with-async-fonts

Wrap your root component with FontObserver:

Set prop with font name. You can access it later in FontSubscriber to check if it's ready.

import { FontObserver } from 'react-with-async-fonts';
import { render } from 'react-dom';
import App from './app';
 
render(
  <FontObserver openSans="Open Sans">
    <App />
  </FontObserver>,
  document.getElementById('root'),
);

Wrap your target with FontSubscriber component:

Tip: you can also use withFonts API if you're really into HoCs.

Note that FontSubscriber uses children render prop. Provided function would be called with single argument which is an object with loaded font keys.

import { FontSubscriber } from 'react-with-async-fonts';
 
const Heading = ({ children }) => (
  <FontSubscriber>
    {fonts => (
      <h1 className={fonts.openSans ? 'opens-sans-font' : 'system-font'}>
        {children}
      </h1>
    )}
  </FontSubscriber>
);
 
export default Heading;

API

`FontObserver` component

import { FontObserver } from 'react-with-async-fonts';

Prop	Type	Description
`text`	`string`	`fontfaceobserver`'s `.load` text options
`timeout`	`number`	`fontfaceobserver`'s `.load` timeout options
`[key]`	`Font \\| string`	Font family string or a `Font` object.

`FontSubscriber` component

import { FontSubscriber } from 'react-with-async-fonts';

Prop	Type	Description
`children`	`(fonts: Object) => React.Element<any>`	Children render function. Accepts object with loaded font. Once ready, it would contain object of `Font` type.

`withFonts` HoC

import { withFonts } from 'react-with-async-fonts';

Argument	Type	Description
component	`React.ComponentType<any>`	Component to wrap with HoC. Injects `fonts` object.

`Font` type

type Font = {
  family: String,
  weight?:
    | 'normal'
    | 'bold'
    | 'bolder'
    | 'lighter'
    | '100'
    | '200'
    | '300'
    | '400'
    | '500'
    | '600'
    | '700'
    | '800'
    | '900',
  style?: 'normal' | 'italic' | 'oblique',
  stretch?:
    | 'normal'
    | 'ultra-condensed'
    | 'extra-condensed'
    | 'condensed'
    | 'semi-condensed'
    | 'semi-expanded'
    | 'expanded'
    | 'extra-expanded'
    | 'ultra-expanded',
};

Examples

Heads up! Each example requires wrapping your app with FontObserver:

import React from 'react';
import { render } from 'react-dom';
import { FontObserver } from 'react-with-async-fonts';
import App from './app';
 
render(
  <FontObserver montserrat="Montserrat">
    <App />
  </FontObserver>,
  document.getElementById('root'),
);

Basic with `FontSubscriber`

import React from 'react';
import { FontSubscriber } from 'react-with-async-fonts';
 
const Heading = ({ children }) => (
  <FontSubscriber>
    {fonts => (
      <h1 className={fonts.montserrat && 'montserrat-font'}>{children}</h1>
    )}
  </FontSubscriber>
);
 
export default Heading;

Basic with `withFonts`

You can use withFonts HoC if you want to compose your component. Please note it uses same FontSubscriber under the hood.

import React from 'react';
import { withFonts } from 'react-with-async-fonts';
 
const Heading = ({ children, fonts }) => (
  <h1 className={fonts.montserrat && 'montserrat-font'}>{children}</h1>
);
 
export default withFonts(Heading);

With `styled-components`

Most elegant way of using it with styled-components is withFonts HoC.

import styled from 'styled-components';
import { withFonts } from 'react-with-async-fonts';
 
const Heading = styled.h2`
  font-weight: 300;
  font-family: ${props =>
    props.fonts.montserrat
      ? '"Open Sans", sans-serif'
      : 'Helvetica, sans-serif'};
`;
 
export default withFonts(Heading);

Nested `FontObserver`

You can nest FontObserver to merge fonts. Children instances overrides parent if font with same code was defined.

import { FontObserver, FontSubscriber } from 'react-with-async-fonts';
 
const Article = ({ title, children }) => (
  <FontObserver roboto="Roboto">
    <FontObserver ptSans="PT Sans">
      <FontSubscriber>
        {fonts => (
          <article>
            <h1 className={fonts.roboto ? 'roboto' : 'sans-serif'}>{title}</h1>
            <p className={fonts.ptSans ? 'ptsans' : 'serif'}>{children}</p>
          </article>
        )}
      </FontSubscriber>
    </FontObserver>
  </FontObserver>
);
 
export default Article;

Custom `fontfaceobserver` options

You can provide text and timeout options for fontfaceobserver's .load method with same props.

import { FontObserver, FontSubscriber } from 'react-with-async-fonts';
 
const Heading = ({ children }) => (
  <FontObserver text={children} timeout={2500} roboto="Roboto">
    <FontSubscriber>
      {fonts => <h1 className={fonts.roboto && 'roboto'}>{children}</h1>}
    </FontSubscriber>
  </FontObserver>
);
 
export default Heading;