Auto fill a box with arbitary text
npm install fontfillBest-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.
``
npm install --save fontfill
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.
This library was written in ECMAScript2015 and the source can be referenced directly like so:
` es6`
import { AutoFittingText } from 'fontfill/src'
You will need your own bundler and transpiler for this to work.
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:
` js`
var AutoFittingText = require('fontfill').AutoFittingText
If you have some requirement for a standalone commonjs2 module:
` js`
var AutoFittingText = require('fontfill').AutoFittingText
if you want to access this module globally
` js`
var AutoFittingText = window.fontfill.AutoFittingText
Here is a pretty straightforward example for a one-time fit
` es6
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('
')
targetDiv.style.fontSize = bestFit.metrics.fontSize
`
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.
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.
* 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
#### 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. |
String to fit
FontFamiy to fit text with
Font Weight to use when calculating token size.
#### .fontMetricsSize : Number
The fontSize to use for calculating fontMetrics (small is
faster, bigger is more precise)
The line height to use when fitting text, as a scalar
Height to constrain text fit to, as a px value.
Width to constrain text fit to, as a px value.
The maximum font size to use when best fitting text as a px value.
The minimum font size to use when best fitting text as a px value.
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 an instance property
| Param | Type | Description |
| --- | --- | --- |
| key | String | Name of reactive property on instance to watch |
| callback | watchCallback | Callback to use |
Set a new, reactive instance property. Should be used instead of
Object.defineProperty()
| Param | Type | Description |
| --- | --- | --- |
| key | String | Property key |
| descriptor | Object | Property descriptor |
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. |
Kind: global external
See: http://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D
___
© 2016 Alex Baker. Documented by jsdoc-to-markdown.