Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/exogen/react-typesetting

React typesetting components.
https://github.com/exogen/react-typesetting

components react typesetting typography

Last synced: 20 days ago
JSON representation

React typesetting components.

Lists

README 

        



# ❧ react-typesetting ☙



React components for creating beautifully typeset designs.



**[Demo!](https://exogen.github.io/react-typesetting)**



---






:warning: This project is highly experimental. Use at your own risk!



## Table of Contents



- [Components](#components)

  * [TightenText](#tightentext)

    + [Props](#props)

  * [PreventWidows](#preventwidows)

    + [Props](#props-1)

  * [Justify](#justify)

    + [Props](#props-2)

  * [FontObserver](#fontobserver)

    + [Props](#props-3)

  * [FontObserver.Provider](#fontobserverprovider)

    + [Props](#props-4)

  * [Typesetting.Provider](#typesettingprovider)

    + [Props](#props-5)



## Components



### TightenText



```js

import { TightenText } from 'react-typesetting';

```



Tightens `word-spacing`, `letter-spacing`, and `font-size` (in that order)

by the minimum amount necessary to ensure a minimal number of wrapped lines

and overflow.



The algorithm starts by setting the minimum of all values (defined by the

`minWordSpacing`, `minLetterSpacing`, and `minFontSize` props) to determine

whether adjusting these will result in fewer wrapped lines or less overflow.

If so, then a binary search is performed (with at most `maxIterations`) to

find the best fit.



By default, element resizes that may necessitate refitting the text are

automatically detected. By specifying the `reflowKey` prop, you can instead

take manual control by changing the prop whenever you’d like the component to

update.



Note that unlike with typical justified text, the fit adjustments must apply

to all lines of the text, not just the lines that need to be tightened,

because there is no way to target individual wrapped lines. Thus, this

component is best used sparingly for typographically important short runs

of text, like titles or labels.



#### Props



Name

Type

Default

Description



className

String



The class to apply to the outer wrapper `span` created by this component.



style

Object



Extra style properties to add to the outer wrapper `span` created by this

component.



children

Node



The content to render.



minWordSpacing

Number

-0.02



Minimum word spacing in ems. Set this to 0 if word spacing should not be

adjusted.



minLetterSpacing

Number

-0.02



Minimum letter spacing in ems. Set this to 0 if word spacing should not

be adjusted.



minFontSize

Number

0.97



Minimum `font-size` in ems. Set this to 1 if font size should not be

adjusted.



maxIterations

Number

5



When performing a binary search to find the optimal value of each CSS

property, this sets the maximum number of iterations to run before

settling on a value.



reflowKey



One of… 


  Number 


  String



If specified, disables automatic reflow so that you can trigger it

manually by changing this value. The prop itself does nothing, but

changing it will cause React to update the component.



reflowTimeout

Number



Debounces reflows so they happen at most this often in milliseconds (at

the end of the given duration). If not specified, reflow is computed

every time the component is rendered.



disabled

Boolean



Whether to completely disable refitting the text. Any fit adjustments

that have already been applied in a previous render will be preserved.



onReflow

Function



A function to call when layout has been recomputed and the text is done

refitting.



preset

String



The name of a preset defined in an outer `Typesetting.Provider`

component. If it exists, default values for all other props will come

from the specified preset.



### PreventWidows



```js

import { PreventWidows } from 'react-typesetting';

```

Prevents [widows](https://www.fonts.com/content/learning/fontology/level-2/text-typography/rags-widows-orphans)

by measuring the width of the last line of text rendered by the component’s

children. Spaces will be converted to non-breaking spaces until the given

minimum width or the maximum number of substitutions is reached.



By default, element resizes that may necessitate recomputing line widths are

automatically detected. By specifying the `reflowKey` prop, you can instead

take manual control by changing the prop whenever you’d like the component to

update.



#### Props



Name

Type

Default

Description



className

String



The class to apply to the outer wrapper `span` created by this component.



style

Object



Extra style properties to add to the outer wrapper `span` created by this

component.



children

Node



The content to render.



maxSubstitutions

Number

3



The maximum number of spaces to substitute.



minLineWidth



One of… 


  Number 


  String 


  Function



15%



The minimum width of the last line, below which non-breaking spaces will

be inserted until the minimum is met.



* **Numbers** indicate an absolute pixel width.

* **Strings** indicate a CSS `width` value that will be computed by

  temporarily injecting an element into the container and determining its

  width.

* **Functions** will be called with relevant data to determine a dynamic

  number or string value to return. This can be used, for example, to

  have different rules at different breakpoints – like a media query.



nbspChar



One of… 


  String 


  React Element 


  Function



\u00A0



A character or element to use when substituting spaces. Defaults to a

standard non-breaking space character, which you should almost certainly

stick with unless you want to visualize where non-breaking spaces are

being inserted for debugging purposes, or adjust their width.



* **String** values will be inserted directly into the existing Text node

  containing the space.

* **React Element** values will be rendered into an in-memory “incubator”

  node, then transplanted into the DOM, splitting up the Text node in

  which the space was found.

* **Function** values must produce a string, Text node, Element node, or

  React Element to insert.



reflowKey



One of… 


  Number 


  String



If specified, disables automatic reflow so that you can trigger it

manually by changing this value. The prop itself does nothing, but

changing it will cause React to update the component.



reflowTimeout

Number



Debounces reflows so they happen at most this often in milliseconds (at

the end of the given duration). If not specified, reflow is computed

every time the component is rendered.



disabled

Boolean



Whether to completely disable widow prevention.



onReflow

Function



A function to call when layout has been recomputed and space substitution

is done.



preset

String



The name of a preset defined in an outer `Typesetting.Provider`

component. If it exists, default values for all other props will come

from the specified preset.



### Justify



```js

import { Justify } from 'react-typesetting';

```



While this may include more advanced justification features in the future, it

is currently very simple: it conditionally applies `text-align: justify` to

its container element (a `
` by default) depending on whether or not there

is enough room to avoid large, unseemly word gaps. The minimum width is

defined by `minWidth` and defaults to 16 ems.



You might also accomplish this with media queries, but this component can

determine the exact width available to the container element instead of just

the entire page.



#### Props






Name

Type

Default

Description



className

String



The class to apply to the outer wrapper element created by this

component.



style

Object



Extra style properties to add to the outer wrapper element created by

this component.



children

Node



The content to render.



as



One of… 


  String 


  Function 


  Object



p



The element type in which to render the supplied children. It must be

a block level element, like `p` or `div`, since `text-align` has no

effect on inline elements. It may also be a custom React component, as

long as it uses `forwardRef`.



minWidth



One of… 


  Number 


  String



16em



The minimum width at which to allow justified text. Numbers indicate an

absolute pixel width. Strings will be applied to an element's CSS in

order to perform the width calculation.



initialJustify

Boolean

true



Whether or not to initially set `text-align: justify` before the

available width has been determined.



reflowKey



One of… 


  Number 


  String



If specified, disables automatic reflow so that you can trigger it

manually by changing this value. The prop itself does nothing, but

changing it will cause React to update the component.



reflowTimeout

Number



Debounces reflows so they happen at most this often in milliseconds (at

the end of the given duration). If not specified, reflow is computed

every time the component is rendered.



disabled

Boolean



Whether to completely disable justification detection. The last

alignment that was applied will be preserved.



onReflow

Function



A function to call when layout has been recomputed and justification

has been applied or unapplied.



preset

String



The name of a preset defined in an outer `Typesetting.Provider`

component. If it exists, default values for all other props will come

from the specified preset.



### FontObserver



```js

import { FontObserver } from 'react-typesetting';

```



A component for observing the fonts specified in the `FontObserver.Provider`

component.



#### Props



Name

Type

Default

Description



children

Function



A function that will receive the current status of the observed fonts.

The argument will be an object with these properties:



- `fonts`: An array of the fonts passed to `FontObserver.Provider`, each

  with a `loaded` and `error` property.

- `loaded`: Whether all observed fonts are done loading.

- `error`: If any fonts failed to load, this will be populated with the

  first error.



### FontObserver.Provider



```js

import { FontObserver } from 'react-typesetting';

```



A context provider for specifying which fonts to observe.



#### Props



Name

Type

Default

Description



fonts



Array of… 


  One of… 


    String 


    Object 1



The fonts to load and observe. The font files themselves should already

be specified somewhere (in CSS), this component simply uses `FontFaceObserver`

to force them to load (if necessary) and observe when they are ready.



Each item in the array specifies the font `family`, `weight`, `style`,

and `stretch`, with only `family` being required. Additionally, each item

can contain a custom `testString` and `timeout` for that font, if they

should differ from the defaults. If only the family name is needed, the

array item can just be a string.



1 Object

familyString

weightOne of… 


  Number 


  String

styleString

stretchString

testStringString

timeoutNumber



testString

String



A custom test string to pass to the `load` method of `FontFaceObserver`,

to be used for all fonts that do not specify their own `testString`.



timeout

Number



A custom timeout in milliseconds to pass to the `load` method of

`FontFaceObserver`, to be used for all fonts that do not specify their

own `timeout`.



children

Node



The content that will have access to font loading status via context.



### Typesetting.Provider



```js

import { Typesetting } from 'react-typesetting';

```



A context provider for defining presets for all other `react-typesetting`

components to use.



#### Props



Name

Type

Default

Description



presets

Object

{}



An object mapping preset names to default props. For example, given the

value:



```js

{ myPreset: { minFontSize: 1, maxIterations: 3 } }

```



…the `TightenText` component could use this preset by specifying the

`preset` prop:



```jsx



```



children

Node



The content that will have access to the defined presets via context.