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: about 2 months ago
JSON representation
React typesetting components.
- Host: GitHub
- URL: https://github.com/exogen/react-typesetting
- Owner: exogen
- License: mit
- Created: 2017-04-02T01:20:00.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2020-03-05T01:15:57.000Z (over 4 years ago)
- Last Synced: 2024-04-18T07:26:00.937Z (5 months ago)
- Topics: components, react, typesetting, typography
- Language: JavaScript
- Homepage: https://exogen.github.io/react-typesetting/
- Size: 3.07 MB
- Stars: 83
- Watchers: 3
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
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
DescriptionclassName
StringThe class to apply to the outer wrapper `span` created by this component.
style
ObjectExtra style properties to add to the outer wrapper `span` created by this
component.children
NodeThe content to render.
minWordSpacing
Number
-0.02Minimum word spacing in ems. Set this to 0 if word spacing should not be
adjusted.minLetterSpacing
Number
-0.02Minimum letter spacing in ems. Set this to 0 if word spacing should not
be adjusted.minFontSize
Number
0.97Minimum `font-size` in ems. Set this to 1 if font size should not be
adjusted.maxIterations
Number
5When 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
StringIf 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
NumberDebounces 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
BooleanWhether to completely disable refitting the text. Any fit adjustments
that have already been applied in a previous render will be preserved.onReflow
FunctionA function to call when layout has been recomputed and the text is done
refitting.preset
StringThe 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
DescriptionclassName
StringThe class to apply to the outer wrapper `span` created by this component.
style
ObjectExtra style properties to add to the outer wrapper `span` created by this
component.children
NodeThe content to render.
maxSubstitutions
Number
3The maximum number of spaces to substitute.
minLineWidth
One of…
Number
String
Function15%
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
StringIf 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
NumberDebounces 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
BooleanWhether to completely disable widow prevention.
onReflow
FunctionA function to call when layout has been recomputed and space substitution
is done.preset
StringThe 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
DescriptionclassName
StringThe class to apply to the outer wrapper element created by this
component.style
ObjectExtra style properties to add to the outer wrapper element created by
this component.children
NodeThe content to render.
as
One of…
String
Function
Objectp
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
String16em
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
trueWhether or not to initially set `text-align: justify` before the
available width has been determined.reflowKey
One of…
Number
StringIf 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
NumberDebounces 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
BooleanWhether to completely disable justification detection. The last
alignment that was applied will be preserved.onReflow
FunctionA function to call when layout has been recomputed and justification
has been applied or unapplied.preset
StringThe 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
Descriptionchildren
FunctionA 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
Descriptionfonts
Array of…
One of…
String
Object 1The 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
timeoutNumbertestString
StringA 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
NumberA 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
NodeThe 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
Descriptionpresets
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
NodeThe content that will have access to the defined presets via context.