fontfill.js

Best-fit any string into a box of arbitrary dimensions. Its a great solution for dynamic display text, responsive websites or a combination of both. Its pretty fast too, resizing a box will look smooth. It also implements a reactive state, so its possible to watch for changes to the fit, such as when the box is resized.

Install

npm install --save fontfill

Getting Started

The primary interface for this library is through a class called AutoFittingText which is detailed below. This package comes with multiple builds that are suitable for a range of use cases, and build tools.

ECMAScript2015

This library was written in ECMAScript2015 and the source can be referenced directly like so:

import { AutoFittingText } from 'fontfill/src'

You will need your own bundler and transpiler for this to work.

ES5

If you are using your own bundler, but don't want to setup an es6 transpiler use the transpiled to ES5 version of this library like so:

var AutoFittingText = require('fontfill').AutoFittingText

commonjs2

If you have some requirement for a standalone commonjs2 module:

var AutoFittingText = require('fontfill').AutoFittingText

Global

if you want to access this module globally

var AutoFittingText = window.fontfill.AutoFittingText

Example

Here is a pretty straightforward example for a one-time fit

import { AutoFittingText } from 'fontfill/src'

const targetString = `Contrary to popular belief, Lorem Ipsum is not simply random text. It has roots in a piece of classical Latin literature from 45 BC, making it over 2000 years old. Richard McClintock, a Latin professor at Hampden-Sydney College in Virginia, looked up one of the more obscure Latin words, consectetur, from a Lorem Ipsum passage, and going through the cites of the word in classical literature, discovered the undoubtable source. Lorem Ipsum comes from sections 1.10.32 and 1.10.33 of "de Finibus Bonorum et Malorum" (The Extremes of Good and Evil) by Cicero, written in 45 BC. This book is a treatise on the theory of ethics, very popular during the Renaissance. The first line of Lorem Ipsum, "Lorem ipsum dolor sit amet..", comes from a line in section 11032.`

const targetDiv = document.body.querySelector('.target-div')
const bestFit = new AutoFittingText(targetDiv.width, targetDiv.height, {
  targetString: targetString,
  family: targetDiv.style.fontFamily
  lineHeight: targetDiv.style.lineHeight // this should be a scalar
})

targetDiv.innerHTML = bestFit.metrics.lines.join('<br/>')
targetDiv.style.fontSize = bestFit.metrics.fontSize

Demo

There is a demo available at demo/index.html folder, that requires that the project be built.

You can build the project by running:

npm install && npm run build

in the root of the project directory.

Development

There are currently 0 unit tests, only an e2e test to check the project has built correctly. Currently I won't be accepting any PRs since the code is still in a prototypical state.

npm run dev

Will watch for changes and rebuild as neccessary, it will also host the demo/dev.html project at localhost:8081/demo/dev.html, which will auto reload on changes to the library.

API Reference

• fontfill
  • ~AutoFittingText ⇐ ReactiveClass
    • new AutoFittingText(width, height, options)
    • .targetString : String
    • .family : String
    • .weight : Number
    • .fontMetricsSize : Number
    • .lineHeight : Number
    • .height : Number
    • .width : Number
    • .maxFontSize : Number
    • .minFontSize : Number
    • .truncatedToken : String
    • .contextFontString : String
    • .tokens : Array.<String>
    • .metrics : TextMetric
    • .window : Window
    • .$watch(key, callback)
    • .$set(key, descriptor)
  • ~TextMetric ⇒ TextMetric

class: AutoFittingText

AutoFittingText is a ReactiveClass, all of its computed getters are memoized, but also correctly invalidated and recalculated when a dependency is changed.

new AutoFittingText(width, height, options)

AutoFittingText Constructor

Param	Type	Default	Description
width	Number		Width to fit in px
height	Number		Height to fit in px
options	Object		Options:
options.lineHeight	Number	1.2	Scalar value for text line height
options.family	String	'Arial'	Name of the font family to use
options.targetString	String	''	String to fit
options.weight	String	'normal'	Weight of string
options.maxFontSize	Number	0	Maximum font size to use when fitting text in px, (use 0 to disable).
options.minFontSize	Number	0	Minimum font size to use when fitting text in px, (use 0 to disable).
options.window	Number		The window that should be used to measure the text.
options.truncatedToken	String	'...'	String inserted to end of visible text to indicate truncation.

.targetString : String

String to fit

.family : String

FontFamiy to fit text with

.weight : Number

Font Weight to use when calculating token size.

.fontMetricsSize : Number

The fontSize to use for calculating fontMetrics (small is faster, bigger is more precise)

.lineHeight : Number

The line height to use when fitting text, as a scalar

.height : Number

Height to constrain text fit to, as a px value.

.width : Number

Width to constrain text fit to, as a px value.

.maxFontSize : Number

The maximum font size to use when best fitting text as a px value.

.minFontSize : Number

The minimum font size to use when best fitting text as a px value.

.truncatedToken : String

Token to use when text has to be truncated to fit minimum font size

.contextFontString : String

The string to use when setting context font weight

.tokens: (readonly) : Array.<String>

The target string broken into an array of words split by wordDeleminatorRegex

.metrics: (readonly) : TextMetric

The fitted text TextMetric. This is where the calculated best-fit information is stored.

.window: (constant) : Window

The window to use for measuring text.

.$watch(key, callback)

Watch an instance property

Param	Type	Description
key	String	Name of reactive property on instance to watch
callback	watchCallback	Callback to use

.$set(key, descriptor)

Set a new, reactive instance property. Should be used instead of Object.defineProperty()

Param	Type	Description
key	String	Property key
descriptor	Object	Property descriptor

typedef: TextMetric

A type that stores the data of the calculated best fit text.

Properties

Name	Type	Description
lines	Array.<String>	An array of strings, that represent the fitted text line breaks.
fillRatio	Number	a ratio that can be used to fill as much space as possible (by scaling the font)
maxLineWidth	Number	The maximum (scaled) line width allowed
largestLineSize	Number	The larget line width used
targetLines	Number	The number of lines of the fitted text
fontSize	Number	The fontSize to use for the fitted text, this has been scaled by the fillratio.

Externals

CanvasRenderingContext2D

A canvas 2D Rendering Context element.

Kind: global external
See: http://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D

---

© 2016 Alex Baker. Documented by jsdoc-to-markdown.