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 configured in assets/meta/app.config.json, usually under theme.fonts. Font keys are then referenced from control and view styles:

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

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.

---