> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mindset.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Font Customization

> Use custom fonts to create seamless, on-brand embedded agent experiences

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

```javascript theme={null}
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](https://fonts.google.com/). Any font listed there can be used with the `fontFamily` parameter.

<Tip>
  Google Fonts are automatically loaded and cached by the SDK—no additional setup required.
</Tip>

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

```javascript theme={null}
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

| Parameter        | Type   | Required | Description                                                                     |
| ---------------- | ------ | -------- | ------------------------------------------------------------------------------- |
| `fontWeight`     | Number | Yes      | The weight of the font (e.g., 400 for regular, 600 for semi-bold, 700 for bold) |
| `sha256Checksum` | String | Yes      | SHA-256 checksum of the font file for integrity verification                    |
| `fontUrl`        | String | Yes      | Publicly accessible URL where the font file is hosted                           |
| `fileSize`       | Number | Yes      | Size of the font file in bytes                                                  |
| `fontStyle`      | String | Yes      | Style of the font: `'normal'` or `'italic'`                                     |

### Generating Required Metadata

**SHA-256 Checksum (Linux/Mac):**

```bash theme={null}
shasum -a 256 "$filename" | cut -d' ' -f1
```

**File Size (Linux/Mac):**

```bash theme={null}
wc -c < "$filename" | tr -d ' '
```

<Warning>
  **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.
</Warning>

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

```javascript theme={null}
const customFontTheme = {
    fontFamily: 'Merriweather',
    textStyles: {
        titleSmall: {
            fontSize: 18,
            fontWeight: 600,
        }
    }
};
```

This changes only the `titleSmall` style—all other styles remain at their defaults.

<Note>
  You only need to specify the properties you want to override. Unspecified properties will use default values.
</Note>

### Typography Properties

Each text style can include these properties:

| Property        | Type   | Description                                                 |
| --------------- | ------ | ----------------------------------------------------------- |
| `fontSize`      | Number | Font size in pixels                                         |
| `fontWeight`    | Number | Font weight (100-900)                                       |
| `letterSpacing` | Number | Letter spacing in pixels                                    |
| `height`        | Number | Line 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](https://m3.material.io/styles/typography/type-scale-tokens). These tokens define consistent text styles across the interface.

### Default Values

```javascript theme={null}
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 Category | Available Tokens                                  | Usage Examples                                                                                                                                                  |
| -------------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Title**      | `titleLarge`<br />`titleMedium`<br />`titleSmall` | Dialog headers<br />Section titles in carousels and prompts<br />Metadata labels and source titles<br />Zero state messages                                     |
| **Body**       | `bodyMedium`<br />`bodySmall`                     | List items and thread titles<br />Agent details and descriptions<br />Buttons, pills, and labels<br />Follow-up questions and citations<br />Supporting UI text |
| **Label**      | `labelLarge`<br />`labelMedium`<br />`labelSmall` | Content list labels (sources, citations)<br />Feedback form instructions<br />Supplemental text in disclaimers<br />Loading states and metadata                 |

<Tip>
  Start by overriding just the tokens that affect your most visible UI elements—typically `titleMedium`, `bodyMedium`, and `labelLarge`.
</Tip>

## Complete Customization Example

Here's a comprehensive example showing Google Fonts with typography overrides:

```javascript theme={null}
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

<Tabs>
  <Tab title="Amazon S3">
    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
    ```
  </Tab>

  <Tab title="Azure Blob Storage">
    Upload fonts to Azure Blob Storage with public access. Use Azure CDN for global distribution.

    **Example URL:**

    ```
    https://youraccount.blob.core.windows.net/fonts/YourFont.ttf
    ```
  </Tab>

  <Tab title="Google Cloud Storage">
    Upload fonts to a GCS bucket with public access. Use Cloud CDN for caching.

    **Example URL:**

    ```
    https://storage.googleapis.com/your-bucket/fonts/YourFont.ttf
    ```
  </Tab>
</Tabs>

### 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
```

<Warning>
  **Not recommended for production.** GitHub has rate limits and is not designed for serving production assets. Use cloud storage with CDN for production applications.
</Warning>

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

<Warning>
  **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.
</Warning>

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