Repository files navigation

opentype.js

It gives you access to theletterforms of text from the browser or Node.js.

Seehttps://opentype.js.org/ for a live demo.

• Create a bézier path out of a piece of text.
• Support for composite glyphs (accented letters).
• Support for WOFF, OTF, TTF (both with TrueTypeglyf and PostScriptcff outlines)
• Support for kerning (Using GPOS or the kern table).
• Support for ligatures.
• Support for TrueType font hinting.
• Support arabic text rendering (See issue #364 & PR #359 #361)
• Support for emojis and other SVG or COLR/CPAL color glyphs
• A low memory mode is available as an option (see #329)
• Runs in the browser and Node.js.

Select one of the following sources in the next example:

• https://opentype.js.org/dist/opentype.js
• https://cdn.jsdelivr.net/npm/opentype.js
• https://unpkg.com/opentype.js

<!-- using global declaration --><scriptsrc="https://your.favorite.cdn/opentype.js"></script><script>opentype.parse(...)</script><!-- using module declaration (need full path) --><scripttype=module>import{parse}from"https://unpkg.com/opentype.js/dist/opentype.mjs";parse(...);</script>

npm install opentype.js

constopentype=require('opentype.js');importopentypefrom'opentype.js'import{load}from'opentype.js'

Using TypeScript?See this example

If you plan on improving or debugging opentype.js, you can:

• Fork theopentype.js repo
• clone your forkgit clone git://github.com/yourname/opentype.js.git
• move into the projectcd opentype.js
• install needed dependencies withnpm install
• make your changes
  • option A: for a simple build, usenpm run build
  • option B: for a development server, usenpm run start and navigate to the/docs folder
• check if all still works fine withnpm run test
• commit and open a Pull Request with your changes. Thank you!

This is done in two steps: first, we load the font file into anArrayBuffer ...

// either from an URLconstbuffer=fetch('/fonts/my.woff').then(res=>res.arrayBuffer());// ... or from filesystem (node)constbuffer=require('fs').promises.readFile('./my.woff');// ... or from an <input type=file id=myfile> (browser)constbuffer=document.getElementById('myfile').files[0].arrayBuffer();

... then we.parse() it into aFont instance

// if running in async context:constfont=opentype.parse(awaitbuffer);console.log(font);// if not running in async context:buffer.then(data=>{constfont=opentype.parse(data);console.log(font);})

// promise-based utility to load libraries using the good old <script> tagconstloadScript=(src)=>newPromise((onload)=>document.documentElement.append(Object.assign(document.createElement('script'),{src, onload})));constbuffer=//...same as previous example...// load wawoff2 if needed, and wait (!) for it to be readyif(!window.Module){constpath='https://unpkg.com/wawoff2@2.0.1/build/decompress_binding.js'constinit=newPromise((done)=>window.Module={onRuntimeInitialized:done});awaitloadScript(path).then(()=>init);}// decompress before parsingconstfont=opentype.parse(Module.decompress(awaitbuffer));

It is also possible to craft a Font from scratch by defining each glyph bézier paths.

// this .notdef glyph is required.constnotdefGlyph=newopentype.Glyph({name:'.notdef',advanceWidth:650,path:newopentype.Path()});constaPath=newopentype.Path();aPath.moveTo(100,0);aPath.lineTo(100,700);// more drawing instructions...constaGlyph=newopentype.Glyph({name:'A',unicode:65,advanceWidth:650,path:aPath});constfont=newopentype.Font({familyName:'OpenTypeSans',styleName:'Medium',unitsPerEm:1000,ascender:800,descender:-200,glyphs:[notdefGlyph,aGlyph]});

Once you have aFont object (from crafting or from.parse()) you can save it back out as file.

// using node:fsfs.writeFileSync("out.otf",Buffer.from(font.toArrayBuffer()));// using the browser to createElement a <a> that will be clickedconsthref=window.URL.createObjectURL(newBlob([font.toArrayBuffer()]),{type:"font/opentype"});Object.assign(document.createElement('a'),{download:"out.otf", href}).click();

A Font represents a loaded OpenType font file. It contains a set of glyphs and methods to draw text on a drawing context, or to get a path representing the text.

• glyphs: an indexed list of Glyph objects.
• unitsPerEm: X/Y coordinates in fonts are stored as integers. This value determines the size of the grid. Common values are2048 and4096.
• ascender: Distance from baseline of highest ascender. In font units, not pixels.
• descender: Distance from baseline of lowest descender. In font units, not pixels.

Create a Path that represents the given text.

• x: Horizontal position of the beginning of the text. (default:0)
• y: Vertical position of thebaseline of the text. (default:0)
• fontSize: Size of the text in pixels (default:72).
• options:{GlyphRenderOptions} passed to each glyph, see below

Options is an optional{GlyphRenderOptions} object containing:

• script: script used to determine which features to apply (default:"DFLT" or"latn")
• language: language system used to determine which features to apply (default:"dflt")
• kerning: if true takes kerning information into account (default:true)
• features: an object withOpenType feature tags as keys, and a boolean value to enable each feature.Currently only ligature features"liga" and"rlig" are supported (default:true).
• hinting: if true uses TrueType font hinting if available (default:false).
• colorFormat: the format colors are converted to for rendering (default:"hexa"). Can be"rgb"/"rgba" forrgb()/rgba() output,"hex"/"hexa" for 6/8 digit hex colors, or"hsl"/"hsla" forhsl()/hsla() output."bgra" outputs an object with r, g, b, a keys (r/g/b from 0-255, a from 0-1)."raw" outputs an integer as used in the CPAL table.
• fill: font color, the color used to render each glyph (default:"black")

Note: there is alsoFont.getPaths() with the same arguments, which returns a list of Paths.

Create a Path that represents the given text.

• ctx: A 2D drawing context, like Canvas.
• x: Horizontal position of the beginning of the text. (default:0)
• y: Vertical position of thebaseline of the text. (default:0)
• fontSize: Size of the text in pixels (default:72).
• options:{GlyphRenderOptions} passed to each glyph, seeFont.getPath()

Options is an optional object containing:

• kerning: iftrue, takes kerning information into account (default:true)
• features: an object withOpenType feature tags as keys, and a boolean value to enable each feature.Currently only ligature features"liga" and"rlig" are supported (default:true).
• hinting: if true uses TrueType font hinting if available (default:false).

Draw the points of all glyphs in the text. On-curve points will be drawn in blue, off-curve points will be drawn in red. The arguments are the same asFont.draw().

Draw lines indicating important font measurements for all glyphs in the text.Black lines indicate the origin of the coordinate system (point 0,0).Blue lines indicate the glyph bounding box.Green line indicates the advance width of the glyph.

Convert the string to a list of glyph objects.Note that there is no strict 1-to-1 correspondence between the string and glyph list due topossible substitutions such as ligatures. The list of returned glyphs can be larger or smaller than the length of the given string.

Convert the character to a Glyph object. Returnsnull if the glyph could not be found. Note that this function assumes that there is a one-to-one mapping between the given character and a glyph; for complex scripts, this might not be the case.

Retrieve the value of thekerning pair between the left glyph (or its index) and the right glyph (or its index). If no kerning pair is found, return0. The kerning value gets added to the advance width when calculating the spacing between glyphs.

Returns the advance width of a text.

This is something different thanPath.getBoundingBox(); for example asuffixed whitespace increases the advancewidth but not the bounding boxor an overhanging letter like a calligraphic 'f' might have a quite largerbounding box than its advance width.

This corresponds tocanvas2dContext.measureText(text).width

• fontSize: Size of the text in pixels (default:72).
• options:{GlyphRenderOptions}, seeFont.getPath()

This allows to manage the palettes and colors in the CPAL table, without having to modify the table manually.

Add a new palette.

• colors: (optional) colors to add to the palette, differences to existing palettes will be filled with the defaultValue.

Deletes a palette by its zero-based index

• paletteIndex: zero-based palette index

Deletes a specific color index in all palettes and updates all layers using that color with the color currently held in the replacement index

• colorIndex: index of the color that should be deleted
• replacementIndex: index (according to the palette before deletion) of the color to replace in layers using the color to be to deleted

Returns the font's cpal table, or false if it does not exist. Used internally.

Mainly used internally. Makes sure that the CPAL table exists or is populated with default values.

• colors: (optional) colors to populate on creationreturnstrue if it was created,false if it already existed.

Extend all existing palettes and the numPaletteEntries value by a number of color slots

• num: number of additional color slots to add to all palettes

Fills a set of palette colors (from a palette index, or a provided array of CPAL color values) with a set of colors, falling back to the default color value, until a given count.It does not modify the existing palette, returning a new array instead! UseFont.palettes.setColor() instead if needed.

• palette: palette index or an Array of CPAL color values to fill the palette with, the rest will be filled with the default color
• colors: array of color values to fill the palette with, in a format supported as an output ofcolorFormat in{GlyphRenderOptions}, seeFont.getPath(). CSS color names are also supported in browser context.
• colorCount: Number of colors to fill the palette with, defaults to the value of the numPaletteEntries field

Returns an array of arrays of color values for each palette, optionally in a specified color format

• colorFormat: (optional) See{GlyphRenderOptions} atFont.getPath(), (default:"hexa")

Get a specific palette by its zero-based index

• index: zero-based index of the color in the palette
• paletteIndex: zero-based palette index (default: 0)
• colorFormat: (optional) See{GlyphRenderOptions} atFont.getPath(), (default:"hexa")

Get a specific palette by its zero-based index

• paletteIndex: zero-based palette index
• colorFormat: (optional) See{GlyphRenderOptions} atFont.getPath(), (default:"hexa")

Set one or more colors on a specific palette by its zero-based index

• index: zero-based color index to start filling from
• color: color value or array of color values in a color notation supported as an output ofcolorFormat in{GlyphRenderOptions}, seeFont.getPath(). CSS color names are also supported in browser context.
• paletteIndex: zero-based palette index (default: 0)

Converts a color value string to a CPAL integer color value

• color: string in a color notation supported as an output ofcolorFormat in{GlyphRenderOptions}, seeFont.getPath(). CSS color names are also supported in browser context.

This allows to manage the color glyph layers in the COLR table, without having to modify the table manually.

Adds one or more layers to a glyph, at the end or at a specific position.

• glyphIndex: glyph index to add the layer(s) to.
• layers: layer object {glyph, paletteIndex}/{glyphID, paletteIndex} or array of layer objects.
• position: position to insert the layers at (will default to adding at the end).

Mainly used internally. Ensures that the COLR table exists and is populated with default values.

Gets the layers for a specific glyph

• glyphIndexReturns an array of{glyph, paletteIndex} layer objects.

Removes one or more layers from a glyph.

• glyphIndex: glyph index to remove the layer(s) from
• start: index to remove the layer at
• end: (optional) if provided, removes all layers from start index to (and including) end index

Sets a color glyph layer's paletteIndex property to a new index

• glyphIndex: glyph in the font by zero-based glyph index
• layerIndex: layer in the glyph by zero-based layer index
• paletteIndex: new color to set for the layer by zero-based index in any palette

Mainly used internally. Updates the colr table, adding a baseGlyphRecord if needed, ensuring that it's inserted at the correct position, updating numLayers, and adjusting firstLayerIndex values for all baseGlyphRecords according to any deletions or insertions.

TheVariationManager handles variable font properties using the OpenType font variation tables.

Activates the default variation by setting its variation data as the font's default render options. Uses the default instance if available; otherwise, it defaults to the coordinates of all axes.

Returns the default coordinates for the font's variation axes.

• Returns: An object mapping axis tags to their default values.

Determines and returns the index of the default variation instance. Returns-1 if it cannot be determined.

• Returns: Integer representing the default instance index or-1.

Just a shortcut forFont.variation.process.getTransform().

Finds the index of the variation instance that matches the provided coordinates, or-1 if none match.

• coordinates: Object with axis tags as keys and variation values as corresponding values.
• Returns: Integer of the matching instance index or-1.

Retrieves a specific variation instance by its zero-based index.

• index: Zero-based index of the variation instance.
• Returns: Object representing the variation instance, ornull if the index is invalid.

Sets the variation coordinates to be used by default for rendering in the font's default render options.

• instanceIdOrObject: Either the zero-based index of a variation instance or an object mapping axis tags to variation values.

Gets the current variation settings from the font's default render options.

• Returns: Object with the current variation settings.

TheVariationProcessor is a component of theVariationManager, used mainly internally for computing and applying variations to the glyphs in a variable font. It handles transformations and adjustments based on the font's variable axes and instances.

Returns normalized coordinates for the variation axes based on the current settings.

• coords: The coordinates object to normalize (or the variation coords in the font'sdefaultRenderOptions by default)
• Returns: Normalized coordinates as an object mapping axis tags to normalized values.

Interpolates points based on provided deltas and a scalar value.

• points: Array of original points.
• deltas: Array of point deltas.
• scalar: Scalar value for interpolation.
• Returns: Array of interpolated points.

Calculates the interpolated value for a single point given original values, deltas, and a scalar.

• original: Original value of the point.
• deltaValues: Array of delta values for the point.
• scalar: Scalar value for interpolation.
• Returns: Interpolated value.

Applies delta values to shift points.

• points: Array of original points.
• deltas: Array of deltas to apply.
• Returns: Array of shifted points.

Transforms components of a glyph using a specified transformation matrix.

• components: Components of the glyph.
• transformation: Transformation matrix to apply.
• Returns: Transformed components.

Retrieves a transformed copy of a glyph based on the provided variation coordinates, or the glyph itself if no variation was applied

• glyph: Glyph or index of glyph to transform.
• coords: Variation coords object (or the variation coords in the font'sdefaultRenderOptions by default)
• Returns:opentype.Glyph

Calculates the variable adjustment for a given adjustment parameter.

• adjustment: Adjustment parameter.
• Returns: Adjusted value based on current variation settings.

Selects the appropriate delta values from a collection of deltas based on the current variation settings.

• deltas: Collection of delta values.
• Returns: Appropriate delta values for the current settings.

Computes the blend vector for interpolations based on the current settings.

• Returns: Blend vector used for interpolation calculations.

A Glyph is an individual mark that often corresponds to a character. Some glyphs, such as ligatures, are a combination of many characters. Glyphs are the basic building blocks of a font.

• font: A reference to the Font object.
• name: The glyph name (e.g."Aring","five")
• unicode: The primary unicode value of this glyph (can beundefined).
• unicodes: The list of unicode values for this glyph (most of the time this will be1, can also be empty).
• index: The index number of the glyph.
• advanceWidth: The width to advance the pen when drawing this glyph.
• leftSideBearing: The horizontal distance from the previous character to the origin (0, 0); a negative value indicates an overhang
• xMin,yMin,xMax,yMax: The bounding box of the glyph.
• path: The raw, unscaled path of the glyph.

Get a scaled glyph Path object for use on a drawing context.

• x: Horizontal position of the glyph. (default:0)
• y: Vertical position of thebaseline of the glyph. (default:0)
• fontSize: Font size in pixels (default:72).
• options:{GlyphRenderOptions}, seeFont.getPath()
• font: a font object, needed for rendering COLR/CPAL fonts to get the layers and colors

Calculate the minimum bounding box for the unscaled path of the given glyph. Returns anopentype.BoundingBox object that containsx1/y1/x2/y2.If the glyph has no points (e.g. a space character), all coordinates will be zero.

Draw the glyph on the given context.

• ctx: The drawing context.
• x: Horizontal position of the glyph. (default:0)
• y: Vertical position of thebaseline of the glyph. (default:0)
• fontSize: Font size, in pixels (default:72).
• options:{GlyphRenderOptions}, seeFont.getPath()
• font: a font object, needed for rendering COLR/CPAL fonts to get the layers and colors

Draw the points of the glyph on the given context.On-curve points will be drawn in blue, off-curve points will be drawn in red.The arguments are the same asGlyph.draw().

Draw lines indicating important font measurements for all glyphs in the text.Black lines indicate the origin of the coordinate system (point 0,0).Blue lines indicate the glyph bounding box.Green line indicates the advance width of the glyph.The arguments are the same asGlyph.draw().

These are currently only wrapper functions for their counterparts on Path objects (see documentation there), but may be extended in the future to pass on Glyph data for automatic calculation.

Gets the color glyph layers for this glyph from the specified font's COLR/CPAL tables

Once you have a path throughFont.getPath() orGlyph.getPath(), you can use it.

• commands: The path commands. Each command is a dictionary containing a type and coordinates. See below for examples.
• fill: The fill color of the Path. Color is a string representing aCSS color. (default:'black')
• stroke: The stroke color of thePath. Color is a string representing aCSS color. (default:null; the path will not be stroked)
• strokeWidth: The line thickness of thePath. (default:1, but ifstroke isnull no stroke will be drawn)

Draw the path on the given 2D context. This uses thefill,stroke, andstrokeWidth properties of the Path object.

• ctx: The drawing context.

Calculate the minimum bounding box for the given path. Returns anopentype.BoundingBox object that containsx1/y1/x2/y2.If the path is empty (e.g. a space character), all coordinates will be zero.

Convert the Path to a string of path data instructions.Seehttps://www.w3.org/TR/SVG/paths.html#PathData

• options:
  • decimalPlaces: The amount of decimal places for floating-point values. (default:2)
  • optimize: apply some optimizations to the path data, e.g. removing unnecessary/duplicate commands (true/false, default:true)
  • flipY: whether to flip the Y axis of the path data, because SVG and font paths use inverted Y axes. (true: calculate from bounding box,false: disable; default:true)
  • flipYBase: Base value for the base flipping calculation. You'll probably want to calculate this from the font's ascender and descender values. (default: automatically calculate from the path data's bounding box)

Convert the path to an SVG<path> element, as a string.

• options: seePath.toPathData()

Retrieve path from SVG path data.

Either overwriting the path data for an existing path:

constpath=newPath();path.fromSVG('M0 0');

Or creating a new Path directly:

constpath=Path.fromSVG('M0 0');

• pathData: Either a string of SVG path commands, or (only in browser context) anSVGPathElement
• options:
  • decimalPlaces,optimize,flipY,flipYBase: seePath.toPathData()
  • scale: scaling value applied to all command coordinates (default:1)
  • x/y: offset applied to all command coordinates on the x or y axis (default:0)

• Move To: Move to a new position. This creates a new contour. Example:{type: 'M', x: 100, y: 200}
• Line To: Draw a line from the previous position to the given coordinate. Example:{type: 'L', x: 100, y: 200}
• Curve To: Draw a bézier curve from the current position to the given coordinate. Example:{type: 'C', x1: 0, y1: 50, x2: 100, y2: 200, x: 100, y: 200}
• Quad To: Draw a quadratic bézier curve from the current position to the given coordinate. Example:{type: 'Q', x1: 0, y1: 50, x: 100, y: 200}
• Close: Close the path. If stroked, this will draw a line from the first to the last point of the contour. Example:{type: 'Z'}

We useSemVer for versioning.

MIT

We would like to acknowledge the work of others without which opentype.js wouldn't be possible:

• pdf.js: for an awesome implementation of font parsing in the browser.
• FreeType: for the nitty-gritty details and filling in the gaps when the spec was incomplete.
• ttf.js: for hints about the TrueType parsing code.
• CFF-glyphlet-fonts: for a great explanation/implementation of CFF font writing.
• fontkit: for a great implementation of CFF2 parsing and variable font features
• tiny-inflate: for WOFF decompression.
• Microsoft Typography: the go-to reference for all things OpenType.
• Adobe Compact Font Format spec and theAdobe Type 2 Charstring spec: explains the data structures and commands for the CFF glyph format.
• Allcontributors.