This is the technical documentation for Tangram’s fonts block. For an overview of Tangram’s labeling capabilities, see the text entry in the Styles Overview.

fonts

The fonts element is an optional top-level element in the scene file. It has only one kind of sub-element: a named font definition.

A font definition can define a font in one of two ways: through external CSS, or with any number of font face definitions.

external

[JS-only] With this method of defining a font, the value of the font definition is set to “external”:

fonts:
    Poiret One: external

This requires that a corresponding CSS declaration be made in the HTML:

<link href='https://fonts.googleapis.com/css?family=Poiret+One' rel='stylesheet' type='text/css'>

Tangram will identify the externally-loaded typeface by name and make it available for use in text labels.

font face definition

A font face definition may be used as the value of the font definition. This is an object with a number of possible parameters:

  • weight: defaults to normal, may also be bold or a numeric font weight, e.g. 500
  • style: defaults to normal, may also be italic
  • url: the URL to load the font from. For maximum browser compatibility, fonts should be either ttf, otf, or woff (woff2 is currently supported in Chrome and Firefox but not other major browsers). As with other scene resources, url is relative to the scene file.

An example of a font face definition with a single parameter, url:

fonts:
    Montserrat:
        url: https://fonts.gstatic.com/s/montserrat/v7/zhcz-_WihjSQC0oHJ9TCYL3hpw3pgy2gAi-Ip7WPMi0.woff

Example of a font face definition with multiple parameters:

fonts:
    Open Sans:
        - weight: 300
          url: fonts/open sans-300normal.ttf
        - weight: 300
          style: italic
          url: fonts/open sans-300italic.ttf
        - weight: 400
          url: fonts/open sans-400normal.ttf
        - weight: 400
          style: italic
          url: fonts/open sans-400italic.ttf
        - weight: 600
          url: fonts/open sans-600normal.ttf
        - weight: 600
          style: italic
          url: fonts/open sans-600italic.ttf
        - weight: 700
          url: fonts/open sans-700normal.ttf
        - weight: 700
          style: italic
          url: fonts/open sans-700italic.ttf
        - weight: 800
          url: fonts/open sans-800normal.ttf
        - weight: 800
          style: italic
          url: fonts/open sans-800italic.ttf

When font definitions are declared in this way, the fonts from the associated urls will be used when the appropriate combination of font-family, style, and weight parameters are specified in a style’s font block:

draw:
    text:
        font:
            family: Open Sans
            style: italic
            weight: 300

For more, see font parameters.