bricks_upload_font

Phase 2IntermediateComplexity: 4/10

Upload a custom font file (woff2, ttf, otf)

Overview

Uploads a custom web font to Bricks Builder, creating a font family with @font-face variants for different weight and style combinations. Supports woff2 (recommended), woff, ttf, otf, and eot formats.

After uploading, the font becomes available in typography font-family dropdowns throughout Bricks and can be referenced in theme styles, global classes, and inline typography settings.

Each font can have multiple variants (e.g., 400 normal, 400 italic, 700 normal, 700 italic) with files provided as URLs to the font assets.

Key Features

Multi-Variant Support

Upload multiple weight/style variants in a single call. Each variant gets its own @font-face rule with the correct weight and style declarations.

Multiple Formats

Supports woff2, woff, ttf, otf, and eot formats. Bricks generates the appropriate src declarations in the @font-face CSS.

Font Display Control

Configure the CSS font-display property (swap, auto, block, fallback, optional) to control text visibility during font loading.

Immediate Availability

After uploading, the font is immediately available in Bricks typography settings. Use font-family: "YourFont" in theme styles or classes.

When to Use

Adding a custom brand font that is not available in Google Fonts
Uploading self-hosted fonts for GDPR compliance (avoiding Google Fonts CDN)
Adding icon fonts or specialty display fonts
When the design requires specific font weights or styles not available in standard web fonts

Prerequisites

Font files must be accessible via URL (either already uploaded to media library or hosted externally)
At minimum, provide a woff2 file for each variant
Font files should be legally licensed for web use

When NOT to Use

When the font is available in Google Fonts (Bricks loads these natively)
When using Adobe Fonts/Typekit (use bricks_set_adobe_fonts instead)
When using system/web-safe fonts (no upload needed)

Parameters

3 Total Parameters2 Required1 Optional

font_familystringREQUIRED

Font family name (e.g., "Inter", "Montserrat", "Custom Font"). This is the CSS font-family value used to reference the font.

font_displaystringoptional

CSS font-display property. Controls text visibility during font loading. "swap" is recommended for performance — shows fallback text immediately, swaps when font loads.

Default: swap Values: swap, auto, block, fallback, optional

variantsarrayREQUIRED

Array of font variant objects. Each variant has: weight (string: "100"-"900", "normal", "bold"), style (enum: "normal", "italic", "oblique"), and files (object with format keys: woff2, woff, ttf, otf, eot — each a URL string). At minimum one variant with a woff2 file is required.

Code Examples

Upload a custom font with two weights

Upload a brand font with regular (400) and bold (700) variants in woff2 format.

JSON

{
  "font_family": "BrandFont",
  "font_display": "swap",
  "variants": [
    {
      "weight": "400",
      "style": "normal",
      "files": {
        "woff2": "https://example.com/fonts/brandfont-regular.woff2",
        "woff": "https://example.com/fonts/brandfont-regular.woff"
      }
    },
    {
      "weight": "700",
      "style": "normal",
      "files": {
        "woff2": "https://example.com/fonts/brandfont-bold.woff2",
        "woff": "https://example.com/fonts/brandfont-bold.woff"
      }
    },
    {
      "weight": "400",
      "style": "italic",
      "files": {
        "woff2": "https://example.com/fonts/brandfont-italic.woff2"
      }
    }
  ]
}

Response

{
  "success": true,
  "font_id": "d4e5f6",
  "font_family": "BrandFont",
  "message": "Font 'BrandFont' created with 3 variants."
}

Common Mistakes

Warning: Undefined array key "fix_description" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 47

Deprecated: preg_replace(): Passing null to parameter #3 ($subject) of type array|string is deprecated in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-includes/kses.php on line 1935

Warning: Undefined array key "wrong_code" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 48

Warning: Undefined array key "right_code" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 49

Always include woff2 files — they offer the best compression and are supported by all modern browsers. Fall back to woff or ttf only for legacy support.

Warning: Undefined array key "fix_description" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 47

Deprecated: preg_replace(): Passing null to parameter #3 ($subject) of type array|string is deprecated in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-includes/kses.php on line 1935

Warning: Undefined array key "wrong_code" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 48

Warning: Undefined array key "right_code" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 49

Use standard CSS weight values: "100" through "900", or "normal" (400) and "bold" (700). Arbitrary values like "450" may not render correctly.

Warning: Undefined array key "fix_description" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 47

Deprecated: preg_replace(): Passing null to parameter #3 ($subject) of type array|string is deprecated in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-includes/kses.php on line 1935

Warning: Undefined array key "wrong_code" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 48

Warning: Undefined array key "right_code" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 49

After uploading, you still need to reference the font in theme styles or classes: typographyBody: { "font-family": "BrandFont" }. Uploading alone does not apply the font anywhere.

Tips & Warnings

Tip: Use font-display: "swap" (the default) for best performance. This shows fallback text immediately and swaps to the custom font once loaded, avoiding invisible text during loading.

Tip: For GDPR compliance, self-host fonts instead of using Google Fonts CDN. Upload the font files to your media library first using bricks_upload_media, then reference those URLs.

Warning: Ensure you have proper licensing for web use. Some fonts have restrictions on self-hosting or embedding.

Return Values

Field	Type	Description
`success`	boolean	Whether the font was uploaded and registered successfully.
`font_id`	string	The generated ID for the newly created font, used for deletion.
`font_family`	string	The registered font-family name.
`message`	string	Confirmation message with variant count.

Related Tools

Technical Details

Tool ID

bricks_upload_font

API Endpoint

/design-system/fonts

HTTP Method

POST

Namespace

design-system

Source File

design-system/fonts.ts

Version

1.0

Min Bricks Version

1.9

Requires Auth

Yes

Changelog

v1.0

Initial release with multi-variant and multi-format support.

20250101