Position HTML assets and content with the Edit API

Placing text and titles anywhere in your videos is possible using the HTML asset. You can create flexible layouts by setting the position of the asset, the contents and the text alignment.

Using the techniques in this article you can position lower thirds, titles, captions and other text based elements.

You can use cURL or Postman to interact with the examples in this article.

Default HTML clip position

Like other assets, you control the position using the position and offset properties of the parent clip. The clip positioning guide explains in detail, but we will go over it again below.

When you create an HTML asset, it creates a bounding box that contains the HTML content. The content will wrap to fit within the bounding box.

Set the size of the bounding box using the assets width and height properties. Set the background colour using the background property. If you omit the background property it will create a transparent bounding box.

The JSON below creates an image with an HTML asset in its default position. The default position is in the center of the image (viewport). The HTML content is placed in the center of the bounding box and the text is aligned center.

{
  "timeline": {
    "tracks": [
      {
        "clips": [
          {
            "asset": {
              "type": "html",
              "html": "<p>The quick brown fox jumps over the lazy dog</p>",
              "css": "p { font-family: \"Work Sans Light\"; color: #ffffff; font-size: 32px; }",
              "width": 600,
              "height": 200,
              "background": "#5b5b5b"
            },
            "start": 0,
            "length": 1
          }
        ]
      }
    ]
  },
  "output": {
    "format": "png",
    "resolution": "sd"
  }
}

The following image is generated by the API:

In this example we set the output format to png. To generate a video you set the parameter to mp4.

Positioning the HTML clip

If we set the clips "position": "bottom" and Y offset to -0.05, the clip containing the HTML asset is placed at the bottom of the viewport with a small amount of padding. This can be useful for positioning captions or lower thirds.

The JSON below moves HTML asset to the bottom of the viewport:

{
  "timeline": {
    "tracks": [
      {
        "clips": [
          {
            "asset": {
              "type": "html",
              "html": "<p>The quick brown fox jumps over the lazy dog</p>",
              "css": "p { font-family: \"Work Sans Light\"; color: #ffffff; font-size: 32px; }",
              "width": 600,
              "height": 200,
              "background": "#5b5b5b"
            },
            "start": 0,
            "length": 1,
            "position": "bottom",
            "offset": {
              "y": 0.05
            }
          }
        ]
      }
    ]
  },
  "output": {
    "format": "png",
    "resolution": "sd"
  }
}

The following image is created:

Positioning the HTML content

In the previous example you can see the text is vertically centered. What if you want to vertically align the text to the bottom of the bounding box?

The HTML asset has a position property that controls the origin point of the content.

In the updated JSON below we add "position": "bottom" to the HTML asset to set the vertical alignment:

{
  "timeline": {
    "tracks": [
      {
        "clips": [
          {
            "asset": {
              "type": "html",
              "html": "<p>The quick brown fox jumps over the lazy dog</p>",
              "css": "p { font-family: \"Work Sans Light\"; color: #ffffff; font-size: 32px; }",
              "width": 600,
              "height": 200,
              "background": "#5b5b5b",
              "position": "bottom"
            },
            "start": 0,
            "length": 1,
            "position": "bottom",
            "offset": {
              "y": 0.05
            }
          }
        ]
      }
    ]
  },
  "output": {
    "format": "png",
    "resolution": "sd"
  }
}

The text is now aligned to the bottom of the HTML asset:

Position content using CSS

The HTML asset supports a subset of CSS, allowing you to align text using the text-align property. All the examples so far have the text aligned center. What if you want to position the HTML asset to the right, but align text to the left?

The JSON below will place an HTML asset on the right, with content aligned top and text aligned left:

{
  "timeline": {
    "tracks": [
      {
        "clips": [
          {
            "asset": {
              "type": "html",
              "html": "<p>The quick brown fox jumps over the lazy dog</p>",
              "css": "p { text-align: left; font-family: \"Work Sans Light\"; color: #ffffff; font-size: 32px; }",
              "width": 500,
              "height": 200,
              "background": "#5b5b5b",
              "position": "top"
            },
            "start": 0,
            "length": 1,
            "position": "right",
            "offset": {
              "x": -0.04
            }
          }
        ]
      }
    ]
  },
  "output": {
    "format": "png",
    "resolution": "sd"
  }
}

Notice that we added text-align: left to the assets css property. The resulting image is shown below:

Positioning multiple elements in the viewport

Shotstack's HTML engine is limited to simple text styling, tables and basic layouts only. You can not position divs or block level elements within the HTML asset itself. To position multiple elements in the viewport use separate HTML assets.

The JSON below adds two HTML assets positioned independently from each other:

{
  "timeline": {
    "tracks": [
      {
        "clips": [
          {
            "asset": {
              "type": "html",
              "html": "<p>MAIN HEADING</p>",
              "css": "p { font-family: \"Montserrat ExtraBold\"; color: #25d3d0; font-size: 34px; text-align: left; }",
              "width": 600,
              "height": 100
            },
            "start": 0,
            "length": 1,
            "position": "topLeft",
            "offset": {
              "x": 0.1,
              "y": -0.2
            }
          },
          {
            "asset": {
              "type": "html",
              "html": "<p>A sub heading</p>",
              "css": "p { font-family: \"Work Sans Light\"; color: #ffffff; font-size: 28px; text-align: left; }",
              "width": 600,
              "height": 100
            },
            "start": 0,
            "length": 1,
            "position": "bottomLeft",
            "offset": {
              "x": 0.1,
              "y": 0.07
            }
          }
        ]
      }
    ]
  },
  "output": {
    "format": "png",
    "resolution": "sd"
  }
}

The layout below is generated: