FxCanvas Documentation

Appearance

Font Management ​

FxCanvas provides sophisticated font management through the FontFamily and Font classes, allowing you to load custom fonts and create rich text styling. This system supports web fonts, system fonts, and advanced typography features.

WARNING

FxCanvas does not support TTF collections (TrueType collections). Individual faces must be added manually for each variant. Currently, only variants based on weight are supported.

Loading Fonts with FontFamily ​

The FontFamily class manages font loading and provides a modern way to work with fonts. Fonts can be loaded either locally or remotely.

javascript
const calSans = new FontFamily();

The first step to using fonts is very simple: create a FontFamily instance. No extra parameters are required, as all additional information is added via faces. FxCanvas does not check that the faces you add are correlated, so it is your responsibility to build a proper font family from related faces.

For the easiest way to obtain URLs for remote font faces, see Using Google Fonts.

Adding Font Faces ​

javascript
// Add local font face
calSans.addFace('/path/to/font.ttf', {
    weight: 400,
    format: FontMimeType.TTF,
});

// Add remote font face
calSans.addFace('https://example.com/font.ttf', {
    weight: 700,
    format: FontMimeType.TTF,
});

INFO

Font methods can be called even after Font objects are used, as the final font description is encoded in the correct order just before the HTTP request. However, out-of-order declarations can be confusing and should be minimized.

Creating Font Descriptors ​

Use the Font constructor to create styled font instances:

javascript
// Create fonts with different sizes and weights
const cal20px = new Font(20, calSans, { weight: 300 });
const cal24pxBold = new Font(24, calSans, { weight: 700 });

// Set the font
canvas.setFont(cal20px);
canvas.fillText('Regular text', 50, 50);

canvas.setFont(cal24pxBold);
canvas.fillText('Bold text', 50, 100);

The Font constructor takes:

  • size: Font size in pixels
  • family: FontFamily instance
  • options: Additional styling (weight, style, etc.)

Font Weight Matching Required

The weight value in the font descriptor MUST match the weight value for a font face within the specified family. Failing to do so will produce a 400 HTTP error. Better error reporting is a work in progress.

For rendering text with loaded fonts, see Text Rendering.

Using Google Fonts ​

To use Google Fonts in FxCanvas, obtain their TTF URLs using the Google Webfonts Helper API.

Obtaining TTF URLs for Latin Fonts ​

  1. Visit https://gwfh.mranftl.com/fonts and search for the font, e.g., https://gwfh.mranftl.com/fonts/geist.
  2. Modify the URL to access the API: https://gwfh.mranftl.com/api/fonts/geist.
  3. In the JSON response, copy the "ttf" URL from the desired variant in the "variants" array.

The JSON response contains a "variants" array with different font faces by weight. Use the "fontWeight" field for the correct value:

json
{
  "variants": [
    {
      "id": "700",
      "fontFamily": "'Geist'",
      "fontStyle": "normal",
      "fontWeight": "700",
      "ttf": "https://fonts.gstatic.com/s/geist/v4/gyBhhwUxId8gMGYQMKR3pzfaWI_Re-QImpnf.ttf"
    }
  ]
}

If you need to determine weights for local font files, see Determining Font Weights.

Non-Latin Character Sets ​

For fonts with non-Latin characters, select the charset from the UI first, then access the API with the subsets parameter, e.g., https://gwfh.mranftl.com/api/fonts/noto-sans-jp?subsets=japanese. Copy the desired TTF URL.

Using in FxCanvas ​

javascript
const geistFamily = new FontFamily().addFace('https://fonts.gstatic.com/s/geist/v4/gyBhhwUxId8gMGYQMKR3pzfaWI_RnOMImpnf.ttf', {
    weight: 400,
    format: FontMimeType.TTF,
});

WARNING

FxCanvas does not control this service; availability is not guaranteed and their limits apply. However, URLs from Google's CDN can be assumed to be always available.

Determining Font Weights ​

Accurate font weights ensure proper rendering and styling. Font weights are numerical values that define the thickness of font strokes.

Using FontDrop.info ​

To determine the weight of a local TTF font file:

  1. Visit https://fontdrop.info/
  2. Load the font by dropping the file or selecting it manually
  3. Scroll down past the detected languages and select the "Data" tab
  4. Look for "usWeightClass" in the OS/2 table (towards the right of your screen)
  5. Use that value directly as the weight for the font face

Common Weight Values ​

  • 100: Thin
  • 200: Extra Light
  • 300: Light
  • 400: Regular/Normal
  • 500: Medium
  • 600: Semi Bold
  • 700: Bold
  • 800: Extra Bold
  • 900: Black

Example with Geist ​

For the Geist font family, the weights might be:

  • Geist Regular: 400
  • Geist Bold: 700
javascript
// Using determined weight
const geistFamily = new FontFamily()
  .addFace('/path/to/Geist-Regular.ttf', { weight: 400, format: FontMimeType.TTF })
  .addFace('/path/to/Geist-Bold.ttf', { weight: 700, format: FontMimeType.TTF });

Font management in FxCanvas provides powerful typography capabilities while maintaining efficient encoding for server-side rendering.