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

Quick Start

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;
`

API

$3

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

$3

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

$3

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

| Argument | Type | Description |
| --------- | -------------------------- | --------------------------------------------------- |
| component | React.ComponentType | Component to wrap with HoC. Injects fonts object. |

$3

`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',
};
`

Examples

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'),
);
`

$3

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

const Heading = ({ children }) => (

{fonts => (


{children}

export default Heading;
`

$3

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

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

const Heading = ({ children, fonts }) => (


{children}

export default withFonts(Heading);
`

$3

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);
`

$3

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 }) => (



{fonts => (


export default Article;
`

$3

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

`js
import { FontObserver, FontSubscriber } from 'react-with-async-fonts';

const Heading = ({ children }) => (


{fonts =>

{children}

export default Heading;
``

License

MIT © Sergey Bekrin