# custom-fonts-in-emails
[](https://github.com/ladjs/custom-fonts-in-emails/actions/workflows/ci.yml)
[](https://github.com/sindresorhus/xo)
[](https://github.com/prettier/prettier)
[](https://lass.js.org)
[](LICENSE)
**An extremely easy way to use custom fonts in emails without having to use art software.**
## Table of Contents
* [Features](#features)
* [What does this do](#what-does-this-do)
* [Old Approach](#old-approach)
* [New Approach](#new-approach)
* [Examples](#examples)
* [Install](#install)
* [Usage](#usage)
* [Options](#options)
* [textToSvg](#texttosvg)
* [API](#api)
* [`customFonts.setDefaults(options)`](#customfontssetdefaultsoptions)
* [`customFonts.setOptions(options)`](#customfontssetoptionsoptions)
* [`customFonts.svg(options)`](#customfontssvgoptions)
* [`customFonts.img(options)`](#customfontsimgoptions)
* [`customFonts.png(options, scale)`](#customfontspngoptions-scale)
* [`customFonts.png2x(options)`](#customfontspng2xoptions)
* [`customFonts.png3x(options)`](#customfontspng3xoptions)
* [`customFonts.getAvailableFontPaths()`](#customfontsgetavailablefontpaths)
* [`customFonts.getAvailableFontNames()`](#customfontsgetavailablefontnames)
* [`customFonts.customFontsCache`](#customfontscustomfontscache)
* [License](#license)
## Features
* :art: Outputs optimized SVG, PNG, and Base64 inlined images with optional support for [**@2x**](https://github.com/2x) and [**@3x**](https://github.com/3x) Retina versions (uses the incredibly fast and performant [sharp][sharp]).
* :bulb: Automatic smart-detection of font names spelled incorrectly (or with the wrong extension) with 50% accuracy (uses [fast-levenshtein][fast-levenshtein] and checks for at least 50% distance match).
* :crystal\_ball: Detects user, local, network, system fonts, and `node_modules` folder fonts using [os-fonts][os-fonts] and [pkg-up][pkg-up] (e.g. you don't need to write `Arial.ttf`, you can just write `Arial`).
* :tada: Supports all WOFF, OTF, and TTF fonts (both with TrueType `glyf` and PostScript `cff` outlines).
* :sparkles: Use with recommended packages [nodemailer][nodemailer] and [nodemailer-base64-to-s3][nodemailer-base64-to-s3], or simply use [Lad][lad-url] (has this built-in).
* :pear: Pairs great with [font-awesome-assets][font-awesome-assets] and [juice][juice] (see [Lad's][lad-url] usage as an example).
* :white\_check\_mark: Supports offline and missing image support by automatically adding `alt`, `title`, and `style` attributes of `color` and `font-size` based upon the options passed.
## What does this do
* Imagine you find a really cool font on GitHub such as [GoudyBookletter1911][goudybookletter1911], or another font at sites like [DaFont][dafont] or [Font Squirrel][font-squirrel].
* You want to use this font in your emails and write the text "Make something people want" with it to use as a footer graphic. **:tada: Congratulations, because this package lets you do that with basically one line of code!**
* Let's compare the old and new way (thanks to this package) to put custom fonts in emails.
### Old Approach
Here's the old, slow, and convoluted way you'd do this:
1. Typically you'd have to open Photoshop, GIMP, or Sketch (wait for the updates to finish), and then create an image with this text, select the font, color, and then save it as an image.
2. Then upload it somewhere or have to wait until it deploys to production so you have a valid non-local URL (which is prone to caching in Gmail – in other words... if you ever need to make a slight adjustment to it then you have to completely rename the file).
3. Reference the image in your HTML and try to rememember it's dimensions, or have to open up the art software again to get dimensions. What about Retina? What if you need to change the size or color of the font? What if you need to convert points to pixels? Just forget it... It's too complicated and time consuming, and now your emails will look boring like they always did! :frowning: :rage:
### New Approach
:boom: You don't need to do that anymore! :smile: Here's how easy it is:
```js
import customFonts from 'custom-fonts-in-emails';
import path from 'path';
const options = {
text: 'Make something people want',
fontNameOrPath: 'GoudyBookletter1911',
fontColor: 'white',
backgroundColor: '#ff6600',
fontSize: 40
};
customFonts.png2x(options)
.then(console.log)
.catch(console.error);
```
```html
```
You can now use any font in your emails – without having to use art software like Photoshop or Sketch!
It supports system-wide and `node_modules` fonts out of the box, but you can pass a file path if you wish to use a custom non-standard font. You can also customize its kerning, anchor, color/fill, stroke, font size (even in points if needed), add custom attributes to the HTML tag, and more! See [Usage](#usage), [Options](#options), and the [API](#api) reference below for more info.
It even uses the [fast-levenshtein][fast-levenshtein] algorithm to detect the closest match to the spelling of a font (e.g. in case you mispellled `Arial` as `Arail`).
## Examples
Using the options defined in [New Approach](#new-approach) above, the following code provides examples of this package's [API](#api) methods.
| API Method and Preview | Image Type |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `customFonts.svg(options)` | SVG tag `