Skip to content

Measure Text

The "measureText" transform measures the length of a string in pixels. The measurement can be used in downstream layout computations with the filterScoredLabels transform or as a variable collision length for the displace1d transform. It can also provide variable collision widths for the displace2d transform.

Custom fonts can be configured with the same font, fontStyle, and fontWeight properties as the text mark.

Measurements use the active renderer's text geometry, keeping downstream filtering and collision layout consistent with live text.

For an usage example, check the Annotation Tracks notebook.

Parameters

as Required
Type: string

The output field where the measured width is written.

description
Type: string

A description of the transform step. Can be used for documentation and agent context.

field Required
Type: string (field name)

The field that contains the text to be measured.

font
Type: string

The font typeface. Uses the same asynchronously loaded SDF fonts as the "text" mark.

Default: "Lato"

fontSize Required
Type: number | ExprRef

The font size in pixels.

fontStyle
Type: "normal" | "italic"

The font style. Valid values: "normal" and "italic".

Default: "normal"

fontWeight
Type: number | "thin" | "light" | "regular" | "normal" | "medium" | "bold" | "black"

The font weight. The following strings and numbers are valid values: "thin" (100), "light" (300), "regular" (400), "normal" (400), "medium" (500), "bold" (700), "black" (900)

Default: "regular"

Example

The example below shows the source text in the left panel and the measured width in pixels in the right panel.

{
  "description": "Measure text widths in a table-like layout.",

  "data": {
    "values": [
      { "label": "BRCA1" },
      { "label": "GenomeSpy" },
      { "label": "Copy-number profile" },
      { "label": "Structural variant" },
      { "label": "Tumor suppressor gene" }
    ]
  },

  "transform": [
    {
      "type": "measureText",
      "field": "label",
      "font": "Roboto Condensed",
      "fontWeight": "bold",
      "fontSize": 16,
      "as": "width"
    }
  ],

  "resolve": { "scale": { "y": "shared" } },

  "spacing": 24,
  "padding": { "top": 30, "bottom": 10, "left": 10, "right": 10 },

  "encoding": {
    "y": { "field": "label", "type": "ordinal", "axis": null }
  },

  "hconcat": [
    {
      "title": "Text",
      "mark": {
        "type": "text",
        "size": 16,
        "font": "Roboto Condensed",
        "fontWeight": "bold",
        "align": "left"
      },
      "encoding": {
        "text": { "field": "label" }
      }
    },

    {
      "title": "Measured width (px)",
      "mark": {
        "type": "text",
        "size": 14,
        "align": "right"
      },
      "encoding": {
        "text": { "field": "width", "format": ".1f" }
      }
    }
  ]
}