Typesetting Endpoint ~text

The Typesetting Endpoint (https://assets.imgix.net/~text) expands on the existing text formatting parameters by enabling several additional typographic controls: multi-line text, leading, and tracking. It outputs the requested text as an image that can be used with the mark and blend parameters to do compositing on the fly, eliminating the need to create a image for a text overlay ahead of time.

~text requires at least the txt parameter to be set, and as with that parameter, it fully supports Unicode characters to handle additional languages and emoji (Unicode 15.0). When using the Typesetting Endpoint's output as an overlay on another image, you will need to URI-encode the full ~text output URL so that the encoded URL can be appended as the value to mark or blend.

Note: We recommend the following when creating text images for overlays.

  • Use + signs in place of any spaces in the txt and txt-font parameters.
  • Do not pre-encode any of the characters in the text string (the value for txt). Doing so will cause those characters to be double-encoded when the full ~text URL is encoded and the text will not display correctly.
  • If you're using the imgix Sandbox to generate the initial text image, limit yourself to the A-Z a-z 0-9 . - _ characters to avoid double-encoding errors.

All of the text formatting parameters can be used to control the visual formatting of the requested text, and the Typesetting Endpoint has the same formatting defaults as txt with the following additions:

  • Background: transparent
  • Output image width: 200px
  • Output image height: Varies depending on text length (text wraps to width)

Note: We recommend against using the txt-line and txt-line-color parameters when generating text for later use as overlays. Because the text is rasterized to create an image, any subsequent scaling operations will degrade its readability, and this will be especially noticeable if the text is outlined.

Default with txt-color set

http://assets.imgix.net/~text?txt=The+quick+brown+fox+jumps+over+the+lazy+dog.+The+five+boxing+wizards+jump+quickly.&txt-color=4B5E75

Font size/face, color, background, padding, and width parameters applied

https://assets.imgix.net/~text?fm=png&txt-size=36&w=600&txt-font=Avenir+Next+Condensed,Bold&txt=The+quick+brown+fox+jumps+over+the+lazy+dog.+The+five+boxing+wizards+jump+quickly.&txt-pad=30&bg=3D4C5F&txt-color=fff

See the API specification for more information about this parameter's value ranges and format.