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
- 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'),
);
FontSubscriber
Basic with 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;
withFonts
Basic with 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);
styled-components
With 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);
FontObserver
Nested 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;
fontfaceobserver
options
Custom 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;
License
MIT Β© Sergey Bekrin