text-canvas

TextCanvas

With TextCanvas you can render multi-line text to a 2D canvas that will automatically resize to the text dimensions. This can be useful if you need to create a texture to use on a WebGL canvas or even if you just need text to wrap text automatically on a 2D canvas.

Installation

Via Bower

bower install ext-date

Via NPM

npm install text-canvas

Usage

TextCanvas is an UMD module. You can load it into your application either by importing the module, or loading the script in your page.

If you are importing the TextCanvas module via Webpack, Browserify or similar, make sure that the module name text-canvas is being resolved correctly to the Bower or NPM packages folder.

Via ES6 syntax

import TextCanvas from 'text-canvas'

Via CommonJS syntax

var TextCanvas = require('text-canvas')

Via the script tag

<script src="/scripts/TextCanvas.js"></script> // Change the path as necessary

API

TextCanvas.prototype.constructor([String text[, Object style[, Number resolution]]])

Creates an instance of TextCanvas, which you will be able to modify and re-render at any point.

Parameters

Name	Type	Required	Default	Description
text	String	false	''	The text to be rendered on the canvas.
style	Object	false	{}	The style to use when rendering the text.
resolution	Number	false	window.devicePixelRatio	The resolution, or pixel density, of the rendered text.

Returns

TextCanvas - The created instance.

Example

const textCanvas = new TextCanvas('Hello, World!', {fontFamily: 'Arial', wordWrap: 300}, 2)

Properties

TextCanvas.prototype.text = String

Get or set the text that will be rendered. To force line breaks, use the new line character \n.

Returns

String - The text currently set to be rendered.

Example

const text = textCanvas.text // Outputs the text that will be rendered

textCanvas.text = 'Hello, World!' // Sets the text that will be rendered

TextCanvas.prototype.style = Object

Get or set the text style. Setting the style is an additive operation. All the previously existing styles that are not being set will be kept.

Properties

Name	Type	Required	Default	Description
fontFamily	String	false	'sans-serif'	The font family name. Unlike the CSS font-family property, fallback font families are not supported.
fontStyle	String	false	'normal'	The font style. The possible values are normal, italic or oblique.
fontWeight	String/Number	false	'normal'	The font weight. The possible values are normal, bold, or a multiple of 100 from 100 to 900.
fontVariant	String	false	'normal'	The font variant. The possible values are normal or small-caps.
fontSize	Number	false	16	The font size in pixels.
lineHeight	Number	false	fontSize * 1.2	The text line height, in pixels.
textAlign	String	false	'left'	The alignment of the text. The possible values are left, center or right.
textBaseline	String	false	'bottom'	The baseline of the text. The possible values are top, hanging, middle, alphabetic, ideographic or bottom. Changing this value might create some clipping.
textColor	String	false	'black'	The text colour. It can be any CSS colour string supported by the browser.
wordWrap	Boolean/Number	false	false	Set to false to draw all the text in a single line. Setting it to a number will define the maximum line width in pixels.

Returns

Object - The full text style object.

Example

const style = textCanvas.style // Outputs the full text style object

textCanvas.style = {fontSize: 24, fontWeight: 'bold'} // Sets the text style options

TextCanvas.prototype.resolution = Number

Get or set the pixel density or resolution of the canvas. This will affect the dimensions of the canvas.

Returns

Number - The pixel density or resolution at which the text will be rendered.

Example

const resolution = textCanvas.resolution // Outputs the resolution of the canvas

textCanvas.resolution = 2 // Sets the resolution of the canvas

Methods

TextCanvas.prototype.render()

Renders the text to the canvas with the currently set styles and resolution. TextCanvas uses always the same canvas per instance. If you are using the canvas from a previously rendered text you need to take this into consideration because the dimensions and contents of the canvas will change.

Returns

HTMLCanvasElement - The canvas element in which the text was rendered.

Example

const canvas = textCanvas.render()
document.body.appendChild(canvas)

Brower support

TextCanvas, although not tested in all of them, was created using features supported by these browsers.

• Android Browser 4+
• Blackberry Browser 7+
• Chrome 13+
• Firefox 4+
• Internet Explorer 9+
• Opera 12+
• Opera Mini 5+
• Safari 7+

Support

If you want to request new features or find any bugs, please open a ticket on the issues page and I'll review it as soon as possible.

Authors and Contributors

Created by Luís Rodrigues (@MrSlide)

License and copyright

Released under the MIT license

Copyright (c) 2016 Luís Rodrigues