Custom fonts and advanced text options

This page covers custom fonts, Google Fonts, predefined text templates, and text layer flags for images. For styling parameters, color, multi-line text, and special characters, see Text layer options. For the layer syntax itself, see Layer syntax.

Custom fonts

By default, only universally available fonts are supported for text overlays. However, if you want to use a non-standard font, you can upload it to Cloudinary as a raw, authenticated file and then specify the font's full public_id (including extension) as the font for your overlay:

Custom font guidelines

• .ttf, .otf and .woff2 font types are supported.

• Custom fonts must be uploaded as raw, authenticated files.

  Tip

  You can upload custom fonts via the Media Library by creating (or using an existing) signed upload preset where the Delivery type option in the preset is set as Authenticated. You can use this upload preset when uploading files to the Media Library by configuring it as the default Media library upload preset for Raw files.

  

  Alternatively, you can select the signed upload preset you create for custom fonts in the Media Library upload widget's Advanced settings while uploading assets, if that option is enabled for your account.

• If your custom font's public ID includes slashes, specify the public ID path using colons as separators. For example: path1:path2:myfont.ttf.

• Make sure to include the file extension when referencing the public_id of the raw file. The extension must be specified in lower-case letters.

• To make use of bold or italic font styles, upload separate font files for each emphasis style and specify the relevant file in the overlay transformation.

• A custom font is available only to the specific product environment where it was uploaded.

• Underscores are not supported in custom font names. When uploading the font as a raw file, make sure the public_id does not include an underscore.

• As with any asset you upload to Cloudinary, it is your responsibility to make sure you have the necessary license and redistribution rights for any custom fonts you use.

Google Fonts

You can use any font available in the Google Fonts library by appending @google to the font name in your text overlay:

l_text:<font name>@google_<size>:<text string>

For example, to overlay "Enjoy luxury" in white using the Gravitas One Google Font at size 80:

co_white,l_text:Gravitas%20One@google_80:Enjoy%20luxury

All other text overlay styling parameters are supported in combination with Google Fonts, including decoration, alignment, letter spacing, and line spacing.

Google Fonts guidelines

• Font names are case-sensitive and must match exactly as listed on Google Fonts.
• When using the @google syntax, font weight must be specified as a numeric value (e.g. 400, 700) rather than a keyword such as bold or light. The numeric weight must be supported by the chosen font.
• To specify font size and font weight together, include the weight after the size, separated by an underscore. For example, to use Roboto at size 90 with a weight of 600:
  l_text:Roboto@google_90_600:Hello%20World

Predefined text templates

Instead of specifying the styling parameters every time you need to dynamically add a text overlay to an asset, you can use the public ID of a text image created with the text method of the upload API. The same styles that were used to create the text image will also be dynamically applied to the text overlay. The default text string of the text image is also used unless you provide a new text string, which can be useful if you don't want the text string to appear in the URL, or if the text string is very long.

For example, you can create a text image of "Sample text string" in 82 point, red, Roboto bold font, and the public ID of sample_text_style as follows:

This is the resulting text image:

You can then use the sample_text_style style in your text overlay, as follows:

Text layer flags

The text content for text layers is often supplied in real time by your application users or another external source. You may want to use the following flags to help handle these scenarios:

• fl_text_disallow_overflow (images only): As mentioned in layer overflow behavior, you can control whether large image or text layers will result in expanding the size of the delivered image using the fl_no_overflow flag (images only).

  However, for text overlays on images, if you don't want long text to impact the expected delivery image size, but an unexpected trim might risk cutting off essential text, you can apply the fl_text_disallow_overflow flag, which will cause URLs with overflowing text layers to fail and return a 400 (bad request) error that you can check for and handle in your application.

  For more details and examples, see fl_no_overflow and fl_text_disallow_overflow in the Transformation Reference.

• fl_text_no_trim: By default, text layers are tightly trimmed on all sides. In some cases, especially if you add a border around the text, or you are using a gravity for your text layer that might place the text too close to the edge of the layer behind it, you can use the fl_text_no_trim flag to add a small amount of padding around the text overlay string. For example: