help ukraine

We stand with Ukraine! If you're as appalled by Russia's abhorrent attack as we are, please support Ukraine and its people.


On this page

Overlay text anywhere on the image. Adjust the font, style, size, colors and effects. Up to 4 layers can be overlaid.

'text' the sets text to be displayed. The example below is the default small grey text in the bottom right corner. Further down this page, we will change the color, size, weight, and effects to make the text stand out. text here!

Example image with text overlay

That URL contains spaces and an exclamation mark (!), which browsers interpret correctly. Some characters such as $, £, €, #, &, © are not interpreted correctly, so use the ASCII character equivalent instead. See the Special characters section below for a list of common codes.


'text.size' - the width of the text area in percent (%), relative to the image width. This text is 50% of the image width: text&text.size=50%

Example image with 50% text size


'text.color' - the text color, applied as RGB/RGBA or a color name. (See the Color section for an explanation of color options in Sirv.) text&text.size=50&text.color=FFFFFF

Example image with 50% size white text


'text.opacity' - the opacity of the text from 0 (transparent) to 100 (opaque). The default value is '100'. The text on the image below is 50% opacity: text&text.size=50%&text.color=FFFFFF&text.opacity=50%

Example image with 50% size white text with 50% opacity


'text.position' - the location of the text on the image.

Positions are described with the points of a compass, whereby 'north' is the top center. Available values are: center, north, northeast, northwest, south, southeast, southwest, east, and west. The default position is 'southeast' (lower right corner). text&text.size=50%&text.color=FFFFFF&text.position=center

Example image with 50% size white center-positioned text

Alternatively, text can be located anywhere at all, with three further options.

'text.position.x' - the distance from the left and 'text.position.y' sets the distance from the top. You can use either pixels or percent (%), as either positive or negative values. By default, the position is set from the top left: text&text.size=50%&text.color=FFFFFF&text.position.x=52&text.position.y=36&text.position.gravity=northwest

Example image with custom text position

'text.position.gravity' - the compass location from which the text position is adjusted. For example, text can be aligned 50px below the center like so: text&text.size=50%&text.color=FFFFFF&text.position.gravity=center&text.position.y=50

Example text pulled down from center

Multiple lines

'%0A' - add line breaks to your text for showing multiple lines:

Multi-line text overlay


'text.align' - align multiple lines of text to the left, right or center. This example aligns the text right:

Align lines of text

Using metadata

Metadata from your images can be displayed in your text overlays. To see an images meta, add ?info to the end of the URL, like so:

To display metadata in a text overlay, use ${metadata path}. This example displays the copyright information from the metadata:${XMP.AuthorsPosition}

Example metadata text overlay

It's easy to apply metadata as text on your images or spins. Read the image metadata article to see more examples and learn how to do this.

Font options

'' - sets the text font. The default is Open Sans. You can choose from all the fonts in the expansive Google Fonts library and Google Noto library (for foreign characters).

Here is the Bitter font:

Bitter text font

Here is the Noto Sans CJK TC (for Traditional Chinese) from Google Noto fonts:這裡是一些中文文本。&text.size=60& Sans CJK TC

Noto Sans CJK TC text font

'text.font.size' - sets the height of the font in pixels (px). This lets you fix the size so that it has no relation to the image size. In most cases, 'text.size' (see above) is more suitable. The example below sets a height of 18px: text&text.font.size=18

Overlay text font size 18px

'' - can set the font to be italic instead of the default 'normal': text&

Overlay text italic style

'text.font.weight' - change the font weight from the default value of '400'. Options are 300 or light, 400 or normal, 600 or semi-bold, 700 or bold, 800 or extra-bold. This example sets '300': text&text.font.weight=300

Light text font weight

This example sets 'extra-bold': text&text.font.weight=extra-bold

Extra-bold text font weight


'text.outline.width' - sets an outline (in pixels) around the text characters. The default is '0'. text&text.size=50&text.color=FFFFFF&text.outline.width=5

5px outline around text overlay

'text.outline.color' - sets the color of the text outline. The default color is 'black'. Options are explained in the Color section. text&text.size=50&text.outline.width=15&text.color=FFFFFF&text.outline.color=404E01

Colored 15px outline around text overlay

'text.outline.opacity' - is set on a scale from 0 (transparent) to 100 (opaque). The default value is '100'. text&text.size=50&text.outline.width=15&text.outline.color=404E01&text.color=FFFFFF&text.outline.opacity=50

Text overlay with colored 50%-opacity outline

'text.outline.blur' - blurs the edge of the outline. The value is set in pixels with a default value of '0'. text&text.size=50&text.outline.width=15&text.outline.color=404E01&text.color=FFFFFF&text.outline.blur=10

Text overlay with colored blurred outline


You can add a background area behind the text by using 'text.background.color' to choose a color (see the Color section) and text.background.opacity to set the opacity (default is transparent). text&text.size=50&text.color=white&text.background.color=874A05&text.background.opacity=50

Text overlay with colored 50%-opacity background

'text.background.opacity' is on a scale from 0 (transparent) to 100 (opaque). This example makes the background solid: text&text.size=50&text.color=white&text.background.color=874A05&text.background.opacity=100

Text overlay with solid colored background

Base64 text encoding

You can embed a wider range of characters by using the text.text64 parameter instead of the text parameter.

Encode your text using Base64. Use a Base64 encoding tool if needed. Base64 supports all kinds of characters and glyphs but the font you use must also support those glyphs.

The example below adds 3 long hyphen glyphs ⎯⎯⎯ before and after the text. The Unicode character is U+23AF, which is 4o6v in Base64. That glyph is supported by a handful of Google Fonts, such as the Gothic A1 font:

Text overlaid on image using Base64 encoding

Was this article helpful?

Get help from a Sirv expert