{title}
{children}
React HoC to handle async loaded fonts
npm install 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
- FontObserver component
- FontSubscriber component
- withFonts HoC
- Font type
- Examples
- Basic with FontSubscriber
- Basic with withFonts
- With styled-components
- Nested FontObserver
- Custom fontfaceobserver options
- License
1. Install react-with-async-fonts:
npm:
``bash`
npm install --save react-with-async-fonts
yarn:
`bash`
yarn add react-with-async-fonts
2. Wrap your root component with FontObserver:
Set prop with font name. You can access it later in FontSubscriber to check if
it's ready.
`js
import { FontObserver } from 'react-with-async-fonts';
import { render } from 'react-dom';
import App from './app';
render(
document.getElementById('root'),
);
`
3. 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.
`js
import { FontSubscriber } from 'react-with-async-fonts';
const Heading = ({ children }) => (
{fonts => (
{children}
)}
);
export default Heading;
`
`js`
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. |
`js`
import { FontSubscriber } from 'react-with-async-fonts';
| Prop | Type | Description |
| ---------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| children | (fonts: Object) => React.Element | Children render function. Accepts object with loaded font. Once ready, it would contain object of Font type. |
`js`
import { withFonts } from 'react-with-async-fonts';
| Argument | Type | Description |
| --------- | -------------------------- | --------------------------------------------------- |
| component | React.ComponentType | Component to wrap with HoC. Injects fonts object. |
`js`
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',
};
Heads up! Each example requires wrapping your app with
FontObserver:
`js
import React from 'react';
import { render } from 'react-dom';
import { FontObserver } from 'react-with-async-fonts';
import App from './app';
render(
document.getElementById('root'),
);
`
`js
import React from 'react';
import { FontSubscriber } from 'react-with-async-fonts';
const Heading = ({ children }) => (
{fonts => (
{children}
)}
);
export default Heading;
`
You can use withFonts HoC if you want to compose your component. Please noteFontSubscriber
it uses same under the hood.
`js
import React from 'react';
import { withFonts } from 'react-with-async-fonts';
const Heading = ({ children, fonts }) => (
export default withFonts(Heading);
`
Most elegant way of using it with styled-components is withFonts HoC.
`js
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);
`
You can nest FontObserver to merge fonts. Children instances overrides parent
if font with same code was defined.
`js
import { FontObserver, FontSubscriber } from 'react-with-async-fonts';
const Article = ({ title, children }) => ( {children}
{fonts => (
{title}
)}
);
export default Article;
`
You can provide text and timeout options forfontfaceobserver's .load
method with same props.
`js
import { FontObserver, FontSubscriber } from 'react-with-async-fonts';
const Heading = ({ children }) => (
{fonts => {children}
}
);
export default Heading;
``
MIT © Sergey Bekrin