Skip to main content

​
Overview

Font customization lets you match your embedded agent’s typography to your product’s design system. Instead of using default fonts, you can use Google Fonts or host your own custom fonts—creating a seamless experience where agents feel like a native part of your product. You can customize:
  • Font family — Use any Google Font or self-hosted custom font
  • Font weights and styles — Define multiple weights (regular, bold, etc.) and styles (normal, italic)
  • Typography scale — Override font sizes, weights, letter spacing, and line heights for specific UI elements

​
Quick Start: Using Google Fonts

The simplest way to customize fonts is to use a Google Font. Just specify the font family name in your SDK initialization.

​
Basic Example

const myCustomFontTheme = {
    fontFamily: 'Merriweather'
};

mindset.init({
    customFontTheme: myCustomFontTheme,
    // ... other initialization parameters
});
This applies the Merriweather font from Google Fonts to your entire agent UI.

​
Available Google Fonts

Browse the complete library of Google Fonts at fonts.google.com. Any font listed there can be used with the fontFamily parameter.
Google Fonts are automatically loaded and cached by the SDK—no additional setup required.

​
Using Custom Self-Hosted Fonts

For complete control over typography, you can use self-hosted fonts. This requires hosting the font files yourself and providing additional metadata.

​
Requirements

Before implementing custom fonts, you’ll need:
  • Font files — Font files in .ttf or .otf format
  • Public hosting — A publicly accessible URL where your font files are hosted
  • SHA-256 checksum — The checksum of each font file for integrity verification
  • File size — The exact size of each font file in bytes
  • Licensing — Ensure you have proper licensing for web embedding

​
Implementation

const myCustomFontTheme = {
    fontFamily: 'Firago',
    fontDetails: [
        {
            fontWeight: 600,
            sha256Checksum: '0dda9d907ec201586736814689a387a36fd05ebb87ac6faebdf4f8e4299d3020',
            fontUrl: 'https://raw.githubusercontent.com/bBoxType/FiraGO/master/Fonts/FiraGO_TTF_1001/Italic/FiraGO-SemiBoldItalic.ttf',
            fileSize: 813732,
            fontStyle: 'italic',
        },
        {
            fontWeight: 700,
            sha256Checksum: '51ad0da400568385e038ccb962a692f145dfbd9071d7fe5cb0903fd2a8912ccd',
            fontUrl: 'https://raw.githubusercontent.com/bBoxType/FiraGO/master/Fonts/FiraGO_TTF_1001/Italic/FiraGO-BoldItalic.ttf',
            fileSize: 813028,
            fontStyle: 'italic',
        },
        {
            fontWeight: 500,
            sha256Checksum: '949698ddae3a568f1ada6eed12d5226d448b0b4a6600a44f096cfd9a1aabb555',
            fontUrl: 'https://raw.githubusercontent.com/bBoxType/FiraGO/master/Fonts/FiraGO_TTF_1001/Italic/FiraGO-MediumItalic.ttf',
            fileSize: 813936,
            fontStyle: 'italic',
        }
    ]
};

mindset.init({
    customFontTheme: myCustomFontTheme,
    // ... other initialization parameters
});

​
Font Details Parameters

ParameterTypeRequiredDescription
fontWeightNumberYesThe weight of the font (e.g., 400 for regular, 600 for semi-bold, 700 for bold)
sha256ChecksumStringYesSHA-256 checksum of the font file for integrity verification
fontUrlStringYesPublicly accessible URL where the font file is hosted
fileSizeNumberYesSize of the font file in bytes
fontStyleStringYesStyle of the font: 'normal' or 'italic'

​
Generating Required Metadata

SHA-256 Checksum (Linux/Mac): 
shasum -a 256 "$filename" | cut -d' ' -f1
File Size (Linux/Mac): 
wc -c < "$filename" | tr -d ' '
Provide multiple font weights. If a specific weight is missing, the agent UI will fall back to the closest available weight. For best results, include at least regular (400) and bold (700) weights.

​
Font Character Coverage

When using custom fonts, ensure they include all required characters:
  • Standard alphanumeric characters
  • Special symbols and punctuation
  • Multilingual character sets (if your agents support multiple languages)
Missing characters will fall back to the system font, which may break your design consistency.

​
Customizing Typography Scale

Whether you’re using Google Fonts or custom fonts, you can override specific typography styles used throughout the agent UI.

​
Basic Override Example

const customFontTheme = {
    fontFamily: 'Merriweather',
    textStyles: {
        titleSmall: {
            fontSize: 18,
            fontWeight: 600,
        }
    }
};
This changes only the titleSmall style—all other styles remain at their defaults.
You only need to specify the properties you want to override. Unspecified properties will use default values.

​
Typography Properties

Each text style can include these properties:
PropertyTypeDescription
fontSizeNumberFont size in pixels
fontWeightNumberFont weight (100-900)
letterSpacingNumberLetter spacing in pixels
heightNumberLine height as a multiplier (e.g., 1.5 = 150% of font size)

​
Default Typography Scale

The agent UI uses typography tokens based on the Material 3 Design type scale. These tokens define consistent text styles across the interface.

​
Default Values

const defaultTextStyles = {
    titleLarge: {
        fontSize: 20,
        fontWeight: 500,
        letterSpacing: 0.15,
        height: 1.25,
    },
    titleMedium: {
        fontSize: 18,
        fontWeight: 500,
        letterSpacing: 0.15,
        height: 1.3,
    },
    titleSmall: {
        fontSize: 16,
        fontWeight: 500,
        letterSpacing: 0.15,
        height: 1.35,
    },
    bodyMedium: {
        fontSize: 15,
        fontWeight: 400,
        letterSpacing: 0.15,
        height: 1.6,
    },
    bodySmall: {
        fontSize: 14,
        fontWeight: 400,
        letterSpacing: 0.5,
    },
    labelLarge: {
        fontSize: 16,
        fontWeight: 500,
        letterSpacing: 0.5,
    },
    labelMedium: {
        fontSize: 14,
        fontWeight: 500,
        letterSpacing: 0.3,
        height: 1.4,
    },
    labelSmall: {
        fontSize: 12,
        fontWeight: 400,
        letterSpacing: 0.5,
    },
};

​
Where Typography Tokens Are Used

The agent UI applies these typography tokens to specific interface elements:
Token CategoryAvailable TokensUsage Examples
TitletitleLarge
titleMedium
titleSmall		Dialog headers
Section titles in carousels and prompts
Metadata labels and source titles
Zero state messages
BodybodyMedium
bodySmall		List items and thread titles
Agent details and descriptions
Buttons, pills, and labels
Follow-up questions and citations
Supporting UI text
LabellabelLarge
labelMedium
labelSmall		Content list labels (sources, citations)
Feedback form instructions
Supplemental text in disclaimers
Loading states and metadata
Start by overriding just the tokens that affect your most visible UI elements—typically titleMedium, bodyMedium, and labelLarge.

​
Complete Customization Example

Here’s a comprehensive example showing Google Fonts with typography overrides: 
const myCustomFontTheme = {
    fontFamily: 'Poppins',
    textStyles: {
        titleLarge: {
            fontSize: 22,
            fontWeight: 600,
            letterSpacing: 0.15,
            height: 1.3,
        },
        titleMedium: {
            fontSize: 18,
            fontWeight: 600,
            letterSpacing: 0.15,
            height: 1.3,
        },
        bodyMedium: {
            fontSize: 16,
            fontWeight: 400,
            letterSpacing: 0.15,
            height: 1.6,
        },
        labelLarge: {
            fontSize: 14,
            fontWeight: 500,
            letterSpacing: 0.5,
        },
    }
};

mindset.init({
    customFontTheme: myCustomFontTheme,
    // ... other initialization parameters
});

​
Hosting Custom Fonts

If you’re using self-hosted custom fonts, you’ll need to host them somewhere publicly accessible. Here are recommended hosting options:

​
Recommended: Cloud Storage (Production)

Best for: Production applications with high traffic
Upload fonts to an S3 bucket with public read access. Optionally use CloudFront CDN for better performance.Example URL:
https://your-bucket.s3.amazonaws.com/fonts/YourFont.ttf

​
Alternative: Static Hosting Services

Best for: Small to medium projects, prototyping
  • Netlify / Vercel — Deploy fonts as static assets in your project
  • Cloudflare Pages — Host fonts with automatic global CDN
  • DigitalOcean Spaces — S3-compatible storage with CDN

​
Development Only: GitHub

Best for: Testing and development (not production) Host font files in a public GitHub repository: 
https://raw.githubusercontent.com/username/repo/branch/path-to/font.ttf
Not recommended for production. GitHub has rate limits and is not designed for serving production assets. Use cloud storage with CDN for production applications.

​
Firebase Storage

Upload fonts to Firebase Storage and set them to publicly readable:
  1. Upload font files to Firebase Storage
  2. Set read permissions to public
  3. Generate direct download link from Firebase Console

​
Not Recommended: Google Drive

Avoid Google Drive for font hosting. Google Drive is unreliable for production use, may throttle or block frequent access, and requires converting share links to direct download URLs.

​
Best Practices

​
Font Selection

Match your product’s design system. Use the same font family your product uses to create visual consistency. Provide multiple weights. Include at least regular (400) and bold (700) weights for proper text hierarchy. Test multilingual support. If your agents support multiple languages, verify your font includes all necessary character sets. Check licensing. Ensure you have proper licensing for web embedding before using custom fonts.

​
Performance

Use Google Fonts when possible. They’re automatically optimized, cached, and require no hosting setup. Host custom fonts on a CDN. Use cloud storage with CDN for fast global delivery. Limit font weights. Only include the weights you actually use to reduce load times. Verify file sizes. Large font files (>1MB) can slow down initial load. Consider using subsets or optimized formats.

​
Typography Scale

Start with defaults. Test the default typography scale before customizing. Override selectively. Only customize the tokens that need to match your design system. Maintain readability. Ensure font sizes, weights, and line heights provide comfortable reading experiences. Test across devices. Verify your typography works well on mobile, tablet, and desktop screens.

​
Backward Compatibility

The SDK maintains backward compatibility for font configuration: No customization provided:
  • Uses default Poppins font family
  • Applies default text styles
Font family only (no text styles):
  • Uses provided font family
  • Applies default text styles
Text styles only (no font family):
  • Uses default Poppins font family
  • Applies provided text styles
Font family without font details:
  • Attempts to load as Google Font
  • Falls back to Poppins if not found

​
Troubleshooting

​
Custom font not loading

Possible causes:
  • Font URL is not publicly accessible
  • CORS headers not configured properly
  • Incorrect SHA-256 checksum
  • Incorrect file size
Solution: Verify the font URL is publicly accessible, check hosting service CORS settings, regenerate checksums and file sizes.

​
Font looks incorrect or fallback is used

Possible causes:
  • Missing font weights
  • Font doesn’t include required characters
  • Font style mismatch (normal vs italic)
Solution: Provide multiple font weights in fontDetails. Verify font includes all characters used in your agents. Check that fontStyle parameter matches actual font style.

​
Typography doesn’t match design system

Possible causes:
  • Using wrong typography tokens
  • Not overriding enough properties
  • Line height or letter spacing too different
Solution: Review the typography token usage table. Override font size, weight, and line height together. Test changes incrementally.

​
Performance issues with custom fonts

Possible causes:
  • Font files are too large
  • Hosting service is slow
  • Too many font weights loaded
Solution: Optimize font files or use subsets. Use CDN for font hosting. Limit font weights to those actually needed.