Draw styled text on Canvas

Demo: https://yuneco.github.io/canvas-draw-styled-text/

Features

This package provides a function to draw styled text on Canvas. It supports the following features:

• font size
• font family
• font color
• font weight
• text align: left, center, right
• line height
• writing mode: horizontal-tb, vertical-rl（Japanese 縦書き）
• text decoration: underline, line-through, overline
• extensions: create your custom styles

Note: This package is still in exprimental stage. All the API may change in the future.

Usage

Installation & Import.

To get started, install the package via npm:

npm install @yuneco/canvas-text-styled

Then, import the drawStyledText function in your JS/TS code:

import { drawStyledText, defineText } from '@yuneco/canvas-text-styled'

Drawing Styled Text

// Define your styled text as JSON object.
// defineText is a helper function for TypeScript users.
const sampleText = defineText({
  // text
  text: `Hello, world!
multiline text is supported.`,

  // text box common settings
  setting: {
    lineHeight: 1.5,
    align: 'left',
    direction: 'horizontal',
    // overflow wrap mode. css property 'overflow-wrap' compatible.
    // basically, line breaks at the end of the word. only difference is when a word is longer than the line width.
    // 'normal' (default): word will be overflowed.
    // 'break-word': word will be split at the middle.
    // note: if single character is longer than the line width, it will be overflowed in both cases.
    overflowWrap: 'normal',
    // lang for Intl.Segmenter (used for get char length)
    lang: 'en',
  },

  // extensions.
  // pass an empty object if you don't need it.
  extensions: {},

  // initial style
  initialStyle: {
    fontFamily: 'sans-serif',
    fontSize: 20,
    fontColor: '#333',
    fontWeight: FONT_WEIGHT_NORMAL,
    fontStyle: 'normal',
  },

  // style change instructions.
  // pass an empty array if you don't need it.
  styles: [],
})

// Get the canvas context
const ctx = yourCanvas.getContext('2d')
if (!ctx) {
  throw new Error('Failed to get canvas context')
}

// Draw the text on the canvas at (0, 0) with a wrap width of 300px
drawStyledText(ctx, sampleText, 0, 0, 300)

Using Multiple Styles

You can apply multiple styles to your text:

const sampleText = defineText({
  // text
  text: `Hello, world!
multiline text is supported.`,
  // initial style
  initialStyle: {
    // ...
  },
  // text box common settings
  setting: {
    // ...
  },
  // change style
  styles: [
    // change color to red at 5th character.
    // other style properties are inherited from initialStyle.
    {
      at: 5,
      style: { fontColor: 'red' },
    },
    // change font size to 30px at 10th character.
    // note that fontColor is inherited from previous style.
    {
      at: 10,
      style: { fontSize: 30 },
    },
  ],
})

Using Pre-measured Information for Performance Optimization

The drawStyledText function returns a MeasuredMatrix object, which can be used for performance optimization:

// draw and get mesured info
const mesured = drawStyledText(ctx, sampleText, 0, 0, 300)
// change line height
sampleText.lineHeight *= 1.5
// draw with pre-measured info
drawStyledText(ctx, sampleText, 0, 500, 300, mesured)

The pre-measured information includes line break positions and the size of each character's bounding box. Therefore, it is intended to be reused exclusively for the same text content and under the same wrap width settings. Using it for different text or wrap width configurations may lead to rendering issues or errors.

If you do not anticipate the need to repeatedly draw the same content or if performance optimization is not a concern for your application, you can ignore this feature.

Use Extensions

You can use extensions to add your own custom styles. As an example, canvas-text-styled package provide underLineExtension.

To use the extension, you need to pass it to the extensions property of the defineText function:

import { drawStyledText, defineText, underLineExtension } from '@yuneco/canvas-text-styled'

const sampleText = defineText({
  // text
  text: `Hello, world!
multiline text is supported.`,

  // text box common settings
  setting: {
    /* ... */
  },

  // extensions.
  // pass key-value pairs.
  // key: extension name. you can use any string as this name.
  // value: extension object.
  extensions: {
    underline: underlineExtension,
  },

  // initial style
  initialStyle: {
    fontFamily: 'sans-serif',
    fontSize: 20,
    fontColor: '#333',
    fontWeight: FONT_WEIGHT_NORMAL,
    fontStyle: 'normal',
    // settings for underline extension
    // (only required if you want to use the extension as an initial style)
    underline: true,
  },

  // style change instructions.
  styles: [
    {
      at: 5,
      style: {
        // disable underline at 5th character.
        // this change will be applied until the next style change for underline.
        underline: false,
      },
    },
    {
      at: 10,
      style: {
        // enable underline at 10th character.
        // you can pass an object to customize the style.
        // (options are defined in each extension).
        underline: {
          width: 2,
        },
      },
    },
    {
      at: 15,
      style: {
        // other style changes are not affected to underline extension.
        // so {underline: width: 2} is still applied here.
        color: 'red',
      },
    },
  ],
})

Create Your Own Extensions

You can create your own extensions. An extension is an object that implements the Extension interface. Below is an example of a marker extension that draws a colored line under the text:

import { Extension } from '@yuneco/canvas-text-styled'

/**
 * options for marker extension.
 * if true, default options will be used.
 */
type MarkerOption =
  | true
  | {
      /** marker width as percentage of line height */
      width: number
      /** color of marker */
      color: string
    }

const defaultMarkerLineOption: MarkerOption = {
  width: 50,
  color: '#ff0',
}

/**
 * marker extension.
 */
export const markerExtension: Extension<MarkerOption> = {
  /**
   * Drawing function for the extension.
   * If initialStyle and styles indicate that the extension should be applied,
   * this function will be called before draw text of each segment of the text.
   */
  beforeSegment: (ctx, segment, options) => {
    // check passed option and use the default if necessary.
    const opt = options === true ? defaultMarkerLineOption : { ...defaultMarkerLineOption, ...options }
    // Calculate the position and size of the marker.
    // 2nd parameter includes the text content and the position of the exch character.
    const lh = segment.line.lineMetrix.lineAscent + segment.line.lineMetrix.lineDescent
    const w = (opt.width / 100) * lh
    const y = segment.pos.y + lh - w / 2
    ctx.save()
    ctx.beginPath()
    ctx.lineCap = 'round'
    ctx.strokeStyle = opt.color
    ctx.lineWidth = w
    ctx.moveTo(segment.pos.x + w / 2, y)
    ctx.lineTo(segment.pos.x - w / 2 + segment.text.reduce((sum, c) => sum + c.metrix.width, 0), y)
    ctx.stroke()
    ctx.restore()
  },
}

Matching DOM Text with Canvas Rendering

If you want to display the same text in both a DOM element (e.g., a TipTap/ProseMirror editor) and a canvas, the following CSS properties must be set on the DOM element to match the library's internal measurement. The library handles canvas-side settings automatically.

.your-editor {
  font-kerning: none;
  line-break: strict;
  word-break: normal;
}

• font-kerning: none — The library measures text with kerning disabled. Mismatched kerning causes per-character width differences that accumulate into line break mismatches.
• line-break: strict / word-break: normal — Must match the library's internal css-line-break settings.

For vertical writing mode, set the DOM editor to the browser's normal vertical layout:

.your-editor.vertical {
  writing-mode: vertical-rl;
  text-orientation: mixed;
}

• The library still measures with kerning disabled and uses strict line breaking.
• For canvas rendering in vertical mode, the library internally splits text into runs:
  • ASCII printable characters (U+0020..U+007E) are rendered as sideways
  • graphemes containing Extended_Pictographic (emoji, including ZWJ emoji) are also currently rendered as sideways
  • other graphemes are rendered as mixed
• This split is implemented with offscreen composition because WebKit does not reliably honor per-run text-orientation changes on a single visible canvas.
• Because the DOM element is not run-split the same way, exact DOM/canvas visual matching for vertical text is best-effort rather than pixel-perfect.

Additionally, ensure these values match between the DOM element and the library settings:

DOM CSS	Library Setting	Note
font-family	initialStyle.fontFamily	Must match exactly
font-size	initialStyle.fontSize	In px
line-height	setting.lineHeight	e.g., CSS 1.5 → setting.lineHeight = 1.5

Always wait for fonts to load before drawing:

await document.fonts.ready
drawStyledText(ctx, styledText, x, y, maxWidth)

License

MIT

Contact

https://twitter.com/yuneco