❧ react-typesetting ☙

React components for creating beautifully typeset designs.

---

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

- Components
* TightenText
+ Props
* PreventWidows
+ Props
* Justify
+ Props
* FontObserver
+ Props
* FontObserver.Provider
+ Props
* Typesetting.Provider
+ Props

Components

$3

``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 theminWordSpacing, minLetterSpacing, and minFontSizeprops) to determine whether adjusting these will result in fewer wrapped lines or less overflow. If so, then a binary search is performed (with at mostmaxIterations) to find the best fit.

By default, element resizes that may necessitate refitting the text are automatically detected. By specifying thereflowKeyprop, 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.`

`$3`

`js import { PreventWidows } from 'react-typesetting';`Prevents widows 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 thereflowKeyprop, 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.`

`$3`

`js import { Justify } from 'react-typesetting';`

While this may include more advanced justification features in the future, it is currently very simple: it conditionally appliestext-align: justifyto 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 byminWidth 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.`

`$3`

`js import { FontObserver } from 'react-typesetting';`

A component for observing the fonts specified in the FontObserver.Providercomponent.

#### Props

Name Type Default Description

children

Function

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

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 aloaded and errorproperty. -loaded: Whether all observed fonts are done loading. -error: If any fonts failed to load, this will be populated with the first error.

`$3`

`js import { FontObserver } from 'react-typesetting';`

A context provider for specifying which fonts to observe.

#### Props

Name	Type		Description
fonts	Array of… One of… String Object ¹		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.`
	¹ Object
	family	String
	weight	One of… Number String
	style	String
	stretch	String
	testString	String
	timeout	Number
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.

`$3`

`js import { Typesetting } from 'react-typesetting';`

A context provider for defining presets for all other react-typesettingcomponents to use.

#### Props

Name Type Default Description

presets

Object

{}

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.

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

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

…the TightenTextcomponent could use this preset by specifying thepreset prop:

`jsx``

children

Node

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

`❧ react-typesetting ☙`

React components for creating beautifully typeset designs.

Demo!

---

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

`Table of Contents`

- Components * TightenText + Props * PreventWidows + Props * Justify + Props * FontObserver + Props * FontObserver.Provider + Props * Typesetting.Provider + Props

`Components`

`$3`

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

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

`$3`

`js import { PreventWidows } from 'react-typesetting'; ` Prevents widows 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.`

`$3`

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

`$3`

`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

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

A function that will receive the current status of the observed fonts.
The argument will be an object with these properties:

`$3`

`js import { FontObserver } from 'react-typesetting'; `

A context provider for specifying which fonts to observe.

#### Props

Name	Type		Description
fonts	Array of… One of… String Object ¹		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.`
	¹ Object
	family	String
	weight	One of… Number String
	style	String
	stretch	String
	testString	String
	timeout	Number
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.

`$3`

`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

{}

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.

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

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

…the TightenTextcomponent could use this preset by specifying thepreset prop:

`jsx``

children

Node

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