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_profileandSettings::auto_font_families). A profile you set onConfigyourself always wins. AViewConfigyou pass toAddPanel()keeps its own font families unless it starts fromWindow::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). |
#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.
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:
- Monochrome bitmap fonts. Fonts that provide only bitmap strikes (eg,
.otbfiles, or EBDT tables within.ttfor.woff2files) are treated as pixel fonts. - Grid-aligned outline fonts. Scalable outline fonts whose vector glyphs align with a pixel grid are detected as pixel fonts.
- Color fonts. Multicolored glyphs and emoji are never treated as pixel fonts.
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
emunits don't follow the resized text.
Keeping Authored Font Sizes
You can disable automatic size snapping on your Config before creating the Renderer:
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:
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:
.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-renderinginherits, settingpixelatedonbodystrips antialiasing from every font on the page. Standard body copy will appear jagged. Applypixelateddirectly 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:
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:
- Transformed text. Rotated or skewed text renders with standard antialiasing. Scaling by non-integer factors preserves crisp glyph edges, but spacing between glyphs can fluctuate by a pixel.
- Vertical text. Elements styled with
writing-mode: vertical-rlorvertical-lrdo not guarantee whole-pixel advances. - Constrained canvas text. Passing a
maxWidthargument tofillText()orstrokeText()that compresses text disables whole-pixel spacing. - Unsupported contexts. Text in an
OffscreenCanvasand<select>dropdown menus always usesautorendering.