CanvasRenderingContext2D.fontVariationSettings is not a standard property

[louh]

Thank you for the new variable font support in #495! It helps a lot on my project where the same rendering code runs on both a browser (native canvas) and on the server with this module. With variable font support here, I no longer need to install both fixed and variable width versions of the same font.

One thing I really appreciate about your project is that the API generally follows the browser spec, and I’m hoping that continues to be a goal.

With that said, I'm concerned that the newly added CanvasRenderingContext2D.fontVariationSettings property isn’t part of the standard CanvasRenderingContext2D API. In the browser's implementation of context, font weight is passed through the font shorthand property, as referenced in the original issue, for example:

  ctx.font = `700 45px Roboto Mono`;

The parsing rules for the font property are defined here:
https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/font

Right now, my browser-compatible code must be rewritten to use the non-standard fontVariationSettings property when run with this library. This breaks API parity with the browser and may confuse other developers who are already used to the browser canvas.

Would you consider revisiting this implementation to match the browser spec?

[yisibl]

What specific specification are you referring to? To my knowledge, it hasn't been defined in the HTML specification yet. Please see: whatwg/html#3571

Once the specification is standardized, we can migrate to it.

[louh]

I'm asking specifically to allow ctx.font to be able to set the font weight when using variable fonts.

This works in canvas in the browser:

 ctx.font = `700 45px Roboto Mono`;

The string parsing rules, again, is defined.

But this is not the syntax that is supported in v0.1.83 of this library.

It seems the issue you linked to is recommending that CSS properties like font-variation-settings be usable in the HTML specification of canvas, but it hasn't been adopted. So it's strange that it would be adopted here when it hasn't been standardized in the browser.

[yisibl]

If my understanding of CSS is correct, the font weight algorithm in Canvas aligns with CSS font-weight. The browser searches for fonts within the font family that match the specified weight (there may be multiple options). When setting ctx.font = 700 45px Roboto Mono, if no font matching weight 700(equivalent to bold) is found, the browser uses an algorithm to thicken the glyphs. If skr-canvas isn't working here, that's a different bug.

https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/font-weight#fallback_weights

Although the practice is not well-loved by typographers, bold faces are often synthesized by user agents for families that lack actual bold faces.

CSS Spec

Therefore, this has nothing to do with the variable font API.

[yisibl]

In other words, if you're already using a variable font, avoid using font-weight to achieve bold text. This is because browsers implement boldness through algorithms rather than predefined weights within the font itself, which often fails to accurately reflect the font designer's intent.

In Firefox and Safari, it can also cause text jitter:

2025-12-05.18-52-09.mp4

[louh]

I think we are talking about different things.

There is no fontVariationSettings in the Canvas Context. It does exist in the CSS spec, but not on Canvas. This is not the right way to set font weight in canvas, even for variable fonts.

[Brooooooklyn]

Thanks for raising this concern @louh. You're correct that fontVariationSettings is not part of the standard Canvas 2D API.

However, the standard approach does work in this library. Setting font-weight via ctx.font automatically maps to the variable font's wght axis:

ctx.font = '700 45px Roboto Mono';  // This works for variable fonts
ctx.fillText('Hello World', 50, 100);

The implementation automatically converts the font-weight from ctx.font to the wght variation axis for variable fonts. The same applies to fontStretch → wdth axis.

Precedence rules:

• If only ctx.font weight is set → mapped to wght axis
• If only fontVariationSettings is set → used directly
• If both are set → fontVariationSettings takes precedence

Why fontVariationSettings exists:

While not part of the Canvas spec, it provides access to non-standard variable font axes (like GRAD, CASL, custom axes) that cannot be expressed through ctx.font. As @yisibl mentioned there's an whatwg/html#3571 discussing how to add this capability to the spec, but it hasn't been standardized yet.

We are happy to align our implementation with the standard spec once fontVariationSettings (or an alternative approach) is finalized in the WHATWG HTML specification.