text#

Static text with full typographic styling and optional reveal mask. Inherits everything in common fields; the tables below cover what's specific to text.

interface TextElement extends BaseElement {
  type: "tok-str">'text';
  text?: string;          "tok-cmt">// use this OR spans, not both
  spans?: TextSpan[];

  "tok-cmt">// Typography
  font_family?: string;
  font_size?: number | string;        "tok-cmt">// px, CSS length, or "tok-str">'auto' to fit the box
  font_size_minimum?: number | string;
  font_size_maximum?: number | string;
  font_weight?: number | string;
  font_style?: "tok-str">'normal' | "tok-str">'italic';
  text_transform?: "tok-str">'none' | "tok-str">'uppercase' | "tok-str">'lowercase' | "tok-str">'capitalize';

  "tok-cmt">// Color
  fill_color?: string;
  gradient?: LinearGradient | RadialGradient | ConicGradient;        "tok-cmt">// overrides fill_color
  stroke_color?: string;
  stroke_width?: number;
  stroke_gradient?: LinearGradient | RadialGradient | ConicGradient; "tok-cmt">// overrides stroke_color
  stroke_align?: "tok-str">'center' | "tok-str">'outer' | "tok-str">'inner';                       "tok-cmt">// default "tok-str">'outer'

  "tok-cmt">// Layout
  text_align?: "tok-str">'left' | "tok-str">'center' | "tok-str">'right';
  vertical_align?: "tok-str">'top' | "tok-str">'middle' | "tok-str">'bottom';
  text_wrap?: boolean;
  x_padding?: number | string;
  y_padding?: number | string;
  x_alignment?: number | string;
  y_alignment?: number | string;
  line_height?: number;
  letter_spacing?: number;

  "tok-cmt">// Background band
  background_color?: string;
  background_border_radius?: number;
  background_padding?: number | [number, number];

  "tok-cmt">// Shadow
  text_shadow?: TextShadow | TextShadow[];

  "tok-cmt">// Reveal
  mask?: TextMask;
}

Content#

Spans#

Inline-styled runs for mixed styling within one element — a colored word, a highlighted phrase, exact line breaks. A span whose text is exactly "\n" is a hard line break. Each span inherits the element's typography and color unless it overrides them:

interface TextSpan {
  text: string;
  font_family?: string;
  font_size?: number | string;
  font_weight?: number | string;
  font_style?: "tok-str">'normal' | "tok-str">'italic';
  fill_color?: string;
  letter_spacing?: number;        "tok-cmt">// px tracking; inherits the element's
  background_color?: string;      "tok-cmt">// flat band behind the span
  background?: TextSpanBackground; "tok-cmt">// stylized band (height, inset, skew, radius)
  nowrap?: boolean;               "tok-cmt">// never word-wrap inside this span
}

{
  "type": "text",
  "font_size": 64,
  "spans": [
    { "text": "Ship it " },
    { "text": "today", "fill_color": "#FFD400", "nowrap": true },
    { "text": "." }
  ]
}

Typography#

Color#

Layout#

Background band#

A band drawn behind the glyphs, shrink-wrapped per line. Useful for highlight chips.

Drop shadow#

text_shadow is a per-glyph drop shadow: a single object, or an array of objects rendered back-to-front (last in the array is drawn on top). When unset, no shadow is drawn.

interface TextShadow {
  color: string;
  offset_x?: number;
  offset_y?: number;
  blur?: number;
  opacity?: number;
}

{
  "type": "text",
  "text": "Stacked shadows",
  "text_shadow": [
    { "color": "#000000", "offset_y": 2, "blur": 4, "opacity": 0.6 },
    { "color": "#ff00aa", "offset_x": 4, "offset_y": 4 }
  ]
}

Reveal mask#

Optional mask field for linear-wipe text reveal. Animatable via keyframe_animations on mask.progress.

interface TextMask {
  type: "tok-str">'linear-wipe';
  angle?: number;
  progress?: number | Keyframe[];
  softness?: number;
}

Example: animated text reveal#

{
  "type": "text",
  "text": "Hello, Clipkit.",
  "mask": { "type": "linear-wipe", "angle": -45 },
  "keyframe_animations": [
    {
      "property": "mask.progress",
      "keyframes": [
        { "time": 0,   "value": 0, "easing": "ease-out-quart" },
        { "time": 1.2, "value": 1 }
      ]
    }
  ]
}