React FOUT Stager
Load weights and styles of typefaces in stages. Based on the techniques of @zachleat's work on FOUT with Two Stage Render.
Features
- Load multiple typefaces with weights and styles in potentially multiple stages
- Caches/optimizes repeat views per session with sessionStorage
- Receive event when all fonts have been loaded
- Should work in IE9+
Installation
You can install react-fout-stager
via Yarn or npm:
# If using Yarn: yarn add react-fout-stager # If using npm: npm install --save react-fout-stager
The core component from react-fout-stager is FoutStager
.
This module can be required via ES imports, CommonJS require, or UMD.
; // using requireconst FoutStager = ;
Important! If you need to use the ES5 version, such as within Create React App,
you will need to import the component at react-fout-stager/es5
, e.g.:
; // using requireconst FoutStager = ;
Usage
After importing react-fout-stager, it can be rendered anywhere in the React tree. Once
react-fout-stager will mount, it will kick off loading any typefaces defined in the stages
prop.
import React from 'react';import render from 'react-dom';import FoutStager from 'react-fout-stager'; ;
If you pass any children to FoutStager
, they will not be rendered until the typefaces have all loaded.
import React from 'react';import render from 'react-dom';import FoutStager from 'react-fout-stager'; ;
Props
FoutStager
accepts a few props to customize its behavior:
Property | Type | Required? | Description |
---|---|---|---|
stages |
arrayOf(stage) |
✓ | A list of stages with associated typefaces to load. |
sessionKey |
string |
The sessionStorage key which is used to cache typeface loads. Defaults to foutStagerLoaded . This will need to be overridden if you use multiple FoutStager s in an application. |
|
onStagesLoad |
func |
Execute a function when all typefaces have loaded. | |
children |
node |
Render children when all typefaces have loaded. |
stages
The stages
prop of FoutStager
accepts an array of stages. The shape of a stage is:
Stage :: className: stringisRequired families: isRequired stages:
Or said more verbosely:
- Each stage is an object.
- A stage must include a property named
className
which is astring
class name to place on thehtml
tag when the stage has loaded. - A stage must include a property named
families
which is an array of objects, each of which represents a typeface (font family) to load in this stage. - Each family in
families
must include a property namedfamily
which corresponds to afont-family
defined in CSS. Creating font families is detailed below. - Each family in
families
can optionally include a property namedoptions
, which is an object that defines a font description with properties ofweight
,style
, andstretch
. These accept values that are defined by thefontfaceobserver
library. - A stage can also include a property named
stages
, which is another array of stages to load once the current stage has completed.
All adjacent stages are loaded in parallel. The use of the stages
property on a stage should be use
for loading stages serially.
CSS
In order to load typefaces with FoutStager
, they need to have a defined font-family
in CSS.
For example, here is a @font-face
with a font-family
defined for the Roboto (Regular) typeface:
Take note of the font-family: Roboto
property. This is how you will reference this particular
font in FoutStager
:
<FoutStager = />
Loading variants of a typeface should have their own font-family
name. For example, to define
the Roboto Italic font:
<FoutStager = />
Notice the use of options
when loading fonts with non-normal font descriptions.
Example
This demo can be seen in action on the hosted styleguide.
For a canonical example, we are going to replicate Zach Leatherman's FOFT, or FOUT with Two Stage Render demo in React.
Note: We are loading our CSS from JS using, but this isn't required. /* The purpose of defining class stages is to re-render once a stage has been met. We start with the minimal default stage of sans-serif, and progressively re-render.*/ /* The defined stages now modify the display of elements once they are loaded.*/ /* During stage 1 we only load the Lato font. Once it's loaded, update the body to use it.*/ /* During stage 2 we load Lato Bold, Lato Italic, and Lato Bold Italic. Once these 3 are loaded, we can once again update relevant elements to render using these fonts.*/
import React from 'react';import render from 'react-dom';import FoutStager from 'react-fout-stager';import './lato-family.css'; document);
Development and Contributing
This repository uses Neutrino and the following Neutrino middleware for developing, previewing, and building React components:
To get started:
- Fork and clone this repo.
- Install the dependencies with
yarn
. - Start the development server with
yarn start
. - Use CTRL-C to exit the development server.
- Use
yarn build
to generate the compiled component for publishing to npm.
Feel free to open an issue, submit a pull request, or contribute however you would like. Understand that this documentation is always a work in progress, so file an issue or submit a PR to ask questions or make improvements. Thanks!