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.
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

On GPU-accelerated Views, text above a size cutoff renders analytically through Photon, the GPU vector renderer. Edges stay crisp under any zoom or transform, and CPU Views match this appearance using unhinted outlines and fractional placement so both renderers look near-identical.

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.