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.