Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/sbekrin/react-with-async-fonts
🔠React module for working with custom web fonts
https://github.com/sbekrin/react-with-async-fonts
fontfaceobserver fonts react react-hoc render-prop web-fonts with-async-fonts
Last synced: 3 months ago
JSON representation
🔠React module for working with custom web fonts
- Host: GitHub
- URL: https://github.com/sbekrin/react-with-async-fonts
- Owner: sbekrin
- License: mit
- Created: 2017-04-29T08:03:11.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2019-05-28T20:21:44.000Z (over 5 years ago)
- Last Synced: 2024-05-21T00:59:11.101Z (9 months ago)
- Topics: fontfaceobserver, fonts, react, react-hoc, render-prop, web-fonts, with-async-fonts
- Language: TypeScript
- Homepage: https://npmjs.com/react-with-async-fonts
- Size: 681 KB
- Stars: 22
- Watchers: 3
- Forks: 6
- Open Issues: 6
-
Metadata Files:
- Readme: readme.md
- License: LICENSE
Awesome Lists containing this project
- awesome-react-render-props - react-with-async-fonts
README
# react-with-async-fonts
[](https://www.npmjs.com/package/react-with-async-fonts)
[](https://travis-ci.org/sbekrin/react-with-async-fonts)
[](https://coveralls.io/github/sbekrin/react-with-async-fonts?branch=master)
[](https://greenkeeper.io/)
React module for working with async loaded custom web fonts, based on [`fontfaceobserver`](https://fontfaceobserver.com/).
> 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](#quick-start)
- [API](#api)
- [`FontObserver` component](#fontobserver-component)
- [`FontSubscriber` component](#fontsubscriber-component)
- [`withFonts` HoC](#withfonts-hoc)
- [`Font` type](#font-type)
- [Examples](#examples)
- [Basic with `FontSubscriber`](#basic-with-fontsubscriber)
- [Basic with `withFonts`](#basic-with-withfonts)
- [With `styled-components`](#with-styled-components)
- [Nested `FontObserver`](#nested-fontobserver)
- [Custom `fontfaceobserver` options](#custom-fontfaceobserver-options)
- [License](#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](#withFonts) 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
### `FontObserver` component
```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](#font-type). |
### `FontSubscriber` component
```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](#font-type). |
### `withFonts` HoC
```js
import { withFonts } from 'react-with-async-fonts';
```
| Argument | Type | Description |
| --------- | -------------------------- | --------------------------------------------------- |
| component | `React.ComponentType` | Component to wrap with HoC. Injects `fonts` object. |
### `Font` type
```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`](#fontobserver-component):
```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'),
);
```
### Basic with `FontSubscriber`
```js
import React from 'react';
import { FontSubscriber } from 'react-with-async-fonts';
const Heading = ({ children }) => (
{fonts => (
{children}
)}
);
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.
```js
import React from 'react';
import { withFonts } from 'react-with-async-fonts';
const Heading = ({ children, fonts }) => (
{children}
);
export default withFonts(Heading);
```
### With `styled-components`
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);
```
### Nested `FontObserver`
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 => (
{title}
{children}
)}
);
export default Article;
```
### Custom `fontfaceobserver` options
You can provide `text` and `timeout` options for
[`fontfaceobserver`'s .load](https://github.com/bramstein/fontfaceobserver#how-to-use)
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](http://bekrin.me)