Fonts

Hosanna UI supports flexible font management for TV app development, allowing you to define, configure, and use custom fonts throughout your application.

Font Configuration

Fonts are typically configured in your style configuration files. For example, in static/hosanna-runner/assets/meta/style.config.json, you will find font keys referenced for various UI elements:

"programProgressDescription": {
  "normal": {
    "fontKey": "~theme.fonts.text-regular-16",
    "color": "~theme.colors.grayscale400"
  }
},
"productDetails": {
  "title": {
    "normal": {
      "fontKey": "~theme.fonts.heading-36",
      "color": "~theme.colors.white"
    }
  },
  "description": {
    "normal": {
      "fontKey": "~theme.fonts.text-regular-28",
      "color": "~theme.colors.grayscale300"
    }
  }
}

Font keys such as ~theme.fonts.text-regular-16 or ~theme.fonts.heading-36 are mapped to actual font files and styles in your theme configuration.

Under the Hood: Roku Fonts

Fonts are ultimately Roku SceneGraph fonts. On Roku, we set Font.uri directly or resolve a system font; on Web, the font service registers @font-face entries. The FontManager caches fonts by key for efficient reuse.

Using Fonts in Components

When defining styles for components, use the fontKey property to reference a font from your theme. This ensures consistency and makes it easy to update fonts globally.

Example:

"ActionButton": {
  "default": {
    "normal": {
      "titleFontKey": "~theme.fonts.text-bold-16",
      "color": "~theme.colors.white-45"
    }
  }
}

Tip: Use Font Keys, Not Raw Paths

Bind UI to fontKey (e.g., ~theme.fonts.text-bold-16) rather than hardcoding file paths or sizes. This keeps your theme swappable.

Adding Custom Fonts

To add a new font:

1. Place your font files (.ttf, .otf; web can also use .woff2) in assets/fonts of your app. These are auto-registered on Web.
2. Update your theme configuration to include the new font under the fonts section.
3. Reference the new font using a unique fontKey in your style configuration.

Tip: Trim Glyphs to Reduce Size

Use the support tools to subset your fonts to only required glyph ranges before bundling. See hosanna-ui/support-tools/fonts/trim-fonts.sh.

How FontManager Works

The FontManager resolves a font from a key and caches the result for reuse.

• Key format: "pkg:/assets/fonts/Roboto-Regular.ttf, 28" or system font names like "LargeBold,32".
• If the key contains a URI (or .ttf), it loads by URI; otherwise it resolves a Roku system font (font:<Name>SystemFont).
• Size -1 means keep the intrinsic size; otherwise sets the requested size.

Sequence (high level):

Structure (classes):

Auto-Registration on Web

On Web, the font service scans assets/fonts/*.{ttf,otf} and registers each file via @font-face at startup. Default regular/bold fonts are also registered.

More Usage Examples

Example: Defining a Font in Theme Configuration

"fonts": {
  "text-regular-16": {
    "fontFamily": "Optimistic Display",
    "fontWeight": 400,
    "fontSize": 16
  },
  "heading-36": {
    "fontFamily": "Optimistic Display",
    "fontWeight": 700,
    "fontSize": 36
  }
}

Troubleshooting

• If a font does not appear as expected, ensure the font file is present in your assets and the path is correct in your configuration.
• Check that the fontKey used in your component style matches a key defined in your theme.
• Confirm your files live under assets/fonts so Web auto-registration picks them up.
• Use consistent casing and include the size after a comma when referencing raw fonts.

---