docs

Text Rendering and Fonts

Configure font profiles, tune text weight and contrast, and set default font families.

On this page

You can match text appearance to your target OS, adjust glyph weight and contrast, choose which fonts to use for default CSS families, and more.

📘 AppCore Defaults

In AppCore, App::Create() automatically picks the host platform's font profile and generic font families for new Views (Settings::auto_font_profile and Settings::auto_font_families). A profile you set on Config yourself always wins. A ViewConfig you pass to AddPanel() keeps its own font families unless it starts from Window::default_view_config().

Matching a Platform's Look

Config::font_profile selects a preset for text weight and sharpness. Set it on your Config before creating the Renderer (Creating the Renderer).

Profile Appearance
FontProfile::Default The standard appearance (currently the same as WindowsLike).
FontProfile::WindowsLike The crisp, moderate weight of mainstream browsers on Windows.
FontProfile::MacOSLike The weight and sharpness of Safari and other macOS applications.
FontProfile::Light No weight compensation at all, the thinnest appearance.

Tuning Weight and Contrast

Every text-rendering knob defaults to the value from your chosen font_profile. You can override individual knobs on Config while leaving the rest of the profile untouched— full defaults and ranges are in the Config reference.

Setting Description
font_contrast Thickens the midtones of antialiased edges to increase apparent weight at every size (useful range is 0.0 to 1.0).
font_gamma Compositing gamma for glyphs. Lower values make text heavier, while higher values make it lighter with more edge contrast.
font_embolden Widens glyph stems by a fraction of the font size on light and dark backgrounds without changing text layout. Pixel fonts ignore this while rendering crisply (the default), but use it under PixelFontRendering::Smooth.
font_stem_darkening Boosts coverage to keep thin stems from fading on light backgrounds. Text on dark backgrounds is unaffected.
font_blend_mode Blends antialiased edges using FontBlendMode::GammaCorrected (how Windows browsers composite) or FontBlendMode::SRGB (how macOS composites).
C++
#include <Ultralight/Ultralight.h>

using namespace ultralight;

void Init() {
  Config config;

  ///
  /// Start from the macOS preset, then thicken the midtones a touch.
  /// Every knob we leave alone keeps the preset's value.
  ///
  config.font_profile = FontProfile::MacOSLike;
  config.font_contrast = 0.2;

  ///
  /// Pass our configuration to the Platform singleton before creating
  /// the Renderer.
  ///
  Platform::instance().set_config(config);
}

Which Fonts Pages Use

ViewConfig sets the font family a page receives for generic CSS families and when styling specifies none. By default, font_family_standard is "Times New Roman", font_family_sans_serif is "Arial", and font_family_fixed is "Courier New" (used for <pre> and <code>). The ViewConfig reference lists the remaining generic families along with font_size_default and font_size_fixed.

C++
RefPtr<Renderer> renderer;
RefPtr<View> view;

void CreateView() {
  ///
  /// Point the generic families at fonts we ship with the app.
  ///
  ViewConfig view_config;
  view_config.font_family_sans_serif = "Inter";
  view_config.font_family_fixed = "JetBrains Mono";
  view_config.font_size_fixed = 14;

  view = renderer->CreateView(800, 600, view_config, nullptr);
}

To ship a custom font with your application, a CSS @font-face rule pointing to a file:/// URL is enough for most apps. If you need to manage font discovery and fallbacks programmatically, provide your own font loader (Custom Font Loading)— its fallback font is what a page gets when every other font fails.

Analytic Text and Hinting

GPU Views render text above a size cutoff analytically through Photon (the GPU vector renderer), keeping glyphs crisp under any zoom or transform. CPU Views match this appearance using unhinted outlines and fractional placement so both renderers look nearly identical. The only exception is pixel fonts— both renderers draw them on whole device pixels to keep their edges sharp.

Config::enable_photon_text enables analytic text and is on by default (disabling Config::enable_photon turns it off too). Config::photon_text_min_px sets the size cutoff, which defaults to 16 pixels— smaller glyphs come from a rasterized atlas, and setting it to 0 renders all text analytically.

Config::font_hinting sets the hinting algorithm for those atlas glyphs. The default setting is FontHinting::Normal, which lets your selected font profile choose— every profile disables hinting except FontProfile::Light.

Pixel Fonts

Pixel fonts are designed for pixel art and retro styling. The renderer detects them automatically and renders them with crisp edges without requiring configuration changes or custom CSS.

Detected Font Types

The renderer inspects each font to determine whether it is a pixel font:

Any font not detected as a pixel font renders as standard antialiased text.

Default Appearance

Pixel fonts render with hard edges and no antialiasing across all display scales, including fractional scales (such as 1.25x or 1.5x). They bypass weight adjustments like font_embolden— glyphs keep their crisp weight under every font_profile.

Glyph advances, letter-spacing, tabs, and carets snap to whole device pixels. Because advances fall on whole pixels, total text width at fractional scales can differ slightly from browsers that use fractional positioning.

Font Size Snapping

By default, the renderer adjusts the used font size to the closest size that draws 1:1 on the device pixel grid.

For outline pixel fonts, these 1:1 sizes are the design size and its integer multiples. For bitmap fonts, they are the strike sizes and their integer multiples. If two supported sizes are equally close, the renderer picks the larger size. Any size below half of the smallest 1:1 size remains unchanged.

This adjustment applies at every display scale, including 1x— an authored size that is not a 1:1 multiple changes even without display scaling.

For an outline font with an 8 px design size, the renderer snaps sizes to whole multiples of 8 device pixels:

Display Scale font-size Drawn At
1x 12px 16 px
1.25x 8px 8 device px

Computed styles continue to report the authored size. Queries through getComputedStyle() return the size requested by your CSS.

📘 Layout Changes with Snapping

When the drawn size shifts, layout around the text changes to match the adjusted glyphs. Fixed line heights and boxes sized in em units don't follow the resized text.

Keeping Authored Font Sizes

You can disable automatic size snapping on your Config before creating the Renderer:

C++
void Init() {
  Config config;

  ///
  /// Keep pixel fonts at the size the page asks for.
  ///
  config.snap_pixel_font_size = false;

  Platform::instance().set_config(config);
}

Config::snap_pixel_font_size defaults to true. When set to false, the renderer preserves the exact size requested by CSS and scales glyphs using nearest-neighbor sampling. Edges remain crisp, but if the authored size is not an integer multiple of the design size, some font pixels will draw one device pixel wider than others.

Text styled with -ul-font-rendering: smooth never adjusts its size, regardless of whether snap_pixel_font_size is enabled.

Disabling Crisp Rendering

To render pixel fonts with smoothed edges across the library, assign Config::pixel_font_rendering before creating the Renderer:

C++
void Init() {
  Config config;

  ///
  /// Draw pixel fonts antialiased, like every other font.
  ///
  config.pixel_font_rendering = PixelFontRendering::Smooth;

  Platform::instance().set_config(config);
}

Config::pixel_font_rendering defaults to PixelFontRendering::Pixelated. Setting it to PixelFontRendering::Smooth renders outline pixel fonts with antialiasing and scales bitmap strikes smoothly, giving them the same appearance as standard text.

The -ul-font-rendering Property

Set the -ul-font-rendering CSS property to override rendering behavior on specific elements:

CSS
.hud-score {
  font-family: 'Arcade Pixel';
  -ul-font-rendering: pixelated;
}

.hud-title {
  font-family: 'Arcade Pixel';
  -ul-font-rendering: smooth;
}

The property inherits across child elements and overrides Config::pixel_font_rendering. It accepts three values:

Value Effect
auto Uses automatic detection and the global pixel_font_rendering setting.
smooth Renders glyphs with antialiasing, even when a pixel font is detected.
pixelated Renders detected pixel fonts crisply. Standard non-color fonts render with hard edges and whole-pixel advances.

Color fonts ignore -ul-font-rendering. Unlike standard CSS image-rendering, this property applies only to text.

🚧 Limit Pixelated Styling to Target Elements

Because -ul-font-rendering inherits, setting pixelated on body strips antialiasing from every font on the page. Standard body copy will appear jagged. Apply pixelated directly to elements that use pixel fonts.

Rendering on a Canvas

When drawing text to a 2D canvas, scale the backing store to match the display scale:

JavaScript
const canvas = document.querySelector('canvas');
const ratio = window.devicePixelRatio;

// Give the canvas one backing pixel per device pixel.
canvas.width = Math.round(canvas.clientWidth * ratio);
canvas.height = Math.round(canvas.clientHeight * ratio);

const ctx = canvas.getContext('2d');
ctx.scale(ratio, ratio);
ctx.font = "16px 'Arcade Pixel'";
ctx.fillText('SCORE 1200', 8, 24);

Canvas 2D text inherits the computed -ul-font-rendering value from its <canvas> element.

Sizing the backing canvas to device pixels keeps glyphs sharp on high-DPI and fractional displays. If the backing store uses CSS pixel dimensions, glyphs align to whole canvas pixels but blur when the canvas stretches to fill the display.

Limitations

Pixel font rendering has several layout and transform limitations: