TypeScript Types

Element Types

HTVG supports four element types that can be composed into a tree structure.

Element

Union type representing any HTVG element.

type Element = BoxElement | FlexElement | TextElement | ImageElement;

BoxElement

Block container element for grouping children.

interface BoxElement {
  type: "box";
  style?: BoxStyle;
  children?: Element[];
}

type

'box'

required

Element type identifier

style

BoxStyle

Visual and layout styles

children

Element[]

Child elements to render inside the box

FlexElement

Flexbox container element with flex layout properties.

interface FlexElement {
  type: "flex";
  style?: FlexStyle;
  children?: Element[];
}

type

'flex'

required

Element type identifier

style

FlexStyle

Flexbox layout and visual styles

children

Element[]

Child elements laid out using flexbox

TextElement

Text leaf element with automatic line wrapping.

interface TextElement {
  type: "text";
  content: string;
  style?: TextStyle;
}

type

'text'

required

Element type identifier

content

string

required

Text content to render

style

TextStyle

Typography and color styles

ImageElement

Image element with intrinsic dimensions.

interface ImageElement {
  type: "image";
  src: string;
  width: number;
  height: number;
  style?: ImageStyle;
}

type

'image'

required

Element type identifier

src

string

required

Image source URL or data URI

width

number

required

Intrinsic image width in pixels

height

number

required

Intrinsic image height in pixels

style

ImageStyle

Image display and layout styles

Style Types

BoxStyle

Styles for box container elements.

interface BoxStyle {
  display?: "block" | "flex" | "none";

  width?: Dimension;
  height?: Dimension;
  minWidth?: Dimension;
  maxWidth?: Dimension;
  minHeight?: Dimension;
  maxHeight?: Dimension;

  margin?: Spacing;
  padding?: Spacing;

  backgroundColor?: Color;
  borderWidth?: number;
  borderColor?: Color;
  borderRadius?: BorderRadius;
  opacity?: number;
}

FlexStyle

Styles for flex container elements, including all flexbox properties.

interface FlexStyle {
  display?: "block" | "flex" | "none";

  width?: Dimension;
  height?: Dimension;
  minWidth?: Dimension;
  maxWidth?: Dimension;
  minHeight?: Dimension;
  maxHeight?: Dimension;

  margin?: Spacing;
  padding?: Spacing;

  flexDirection?: FlexDirection;
  justifyContent?: JustifyContent;
  alignItems?: AlignItems;
  gap?: number;
  flexWrap?: FlexWrap;

  backgroundColor?: Color;
  borderWidth?: number;
  borderColor?: Color;
  borderRadius?: BorderRadius;
  opacity?: number;
}

TextStyle

Styles for text elements.

interface TextStyle {
  fontFamily?: string;
  fontSize?: number;
  fontWeight?: FontWeight;
  lineHeight?: number;
  textAlign?: TextAlign;
  color?: Color;
  letterSpacing?: number;
  textRendering?: "text" | "vector";

  flexGrow?: number;
  flexShrink?: number;
}

textRendering

'text' | 'vector'

Render mode: "text" for SVG text elements (default), "vector" for outlined paths

ImageStyle

Styles for image elements.

interface ImageStyle {
  width?: Dimension;
  height?: Dimension;
  minWidth?: Dimension;
  maxWidth?: Dimension;
  minHeight?: Dimension;
  maxHeight?: Dimension;

  margin?: Spacing;

  objectFit?: ObjectFit;

  borderRadius?: BorderRadius;
  opacity?: number;

  flexGrow?: number;
  flexShrink?: number;
}

Primitive Types

Dimension

Dimension value accepting pixels (number) or percentage (string).

type Dimension = number | string;

Examples:

width: 400          // 400 pixels
width: "50%"        // 50% of parent width
height: "100%"      // 100% of parent height

Spacing

Spacing value for margin/padding: uniform number or multi-value string.

type Spacing = number | string;

Examples:

padding: 20                    // 20px all sides
padding: "10 20"               // 10px vertical, 20px horizontal
padding: "10 20 30 40"         // top right bottom left
margin: "0 auto"               // centered horizontally

BorderRadius

Border radius: uniform number or per-corner string.

type BorderRadius = number | string;

Examples:

borderRadius: 8              // 8px all corners
borderRadius: "8 8 0 0"      // top corners rounded, bottom square

Color

CSS color string: hex, rgb(), rgba(), or named colors.

type Color = string;

Examples:

color: "#1a1a1a"                    // hex
color: "#fff"                        // short hex
color: "#ff0000cc"                   // hex with alpha
color: "rgb(255, 0, 0)"              // rgb
color: "rgba(255, 0, 0, 0.8)"        // rgba
color: "red"                         // named color

FontWeight

Font weight: number (100-900) or keyword.

type FontWeight = number | "normal" | "bold";

Examples:

fontWeight: 400        // normal
fontWeight: 700        // bold
fontWeight: "bold"     // keyword

Enum Types

FlexDirection

type FlexDirection = "row" | "column" | "row-reverse" | "column-reverse";

JustifyContent

type JustifyContent =
  | "flex-start"
  | "flex-end"
  | "center"
  | "space-between"
  | "space-around"
  | "space-evenly";

AlignItems

type AlignItems =
  | "flex-start"
  | "flex-end"
  | "center"
  | "stretch"
  | "baseline";

FlexWrap

type FlexWrap = "nowrap" | "wrap";

TextAlign

type TextAlign = "left" | "center" | "right" | "justify";

ObjectFit

type ObjectFit = "contain" | "cover" | "fill";

Document Types

HtvgDocument

Self-contained HTVG document with metadata and content.

interface HtvgDocument {
  meta?: CompileOptions;
  content: Element;
}

CompileOptions

Compilation configuration options.

interface CompileOptions {
  width: number;
  height?: number;
  fontSize?: number;
  fontFamily?: string;
  fonts?: FontSource[];
}

width

number

required

Output width in pixels

height

number

Output height in pixels (auto-computed if omitted)

fontSize

number

default:"16"

Default font size for text elements

fontFamily

string

Default font family for text elements without explicit fontFamily

fonts

FontSource[]

Custom fonts to register

FontSource

Font definition for custom fonts.

interface FontSource {
  family: string;
  url?: string;
  weight?: number;
  data?: string;
}

family

string

required

Font family name (used in SVG @font-face and as identifier)

url

string

URL to the font file (emitted as @font-face src in SVG)

weight

number

default:"400"

Font weight

data

string

Base64-encoded font data (TTF/OTF/WOFF2) used for text layout

Example:

const fonts: FontSource[] = [
  {
    family: "Inter",
    url: "https://fonts.gstatic.com/s/inter/v12/...",
    weight: 400
  },
  {
    family: "Inter",
    url: "https://fonts.gstatic.com/s/inter/v12/...",
    weight: 700
  }
];

CompileResult

Result object returned by compilation functions.

interface CompileResult {
  svg: string;
  width: number;
  height: number;
  warnings: string[];
}

svg

string

Generated SVG string

width

number

Computed output width in pixels

height

number

Computed output height in pixels

warnings

string[]

Array of warning messages from compilation (e.g., missing fonts, invalid values)

Example:

const result: CompileResult = {
  svg: "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"400\" height=\"200\">...</svg>",
  width: 400,
  height: 200,
  warnings: []
};

Complete Example

Here’s a comprehensive example using all type definitions:

import type { 
  HtvgDocument, 
  FlexElement, 
  TextElement, 
  CompileResult,
  FontSource 
} from "htvg";
import { init, compileDocument } from "htvg";

await init();

const customFonts: FontSource[] = [
  {
    family: "Inter",
    url: "https://fonts.gstatic.com/s/inter/v12/UcCO3FwrK3iLTeHuS_fvQtMwCp50KnMw2boKoduKmMEVuLyfAZ9hiA.woff2",
    weight: 600
  }
];

const titleElement: TextElement = {
  type: "text",
  content: "Welcome to HTVG",
  style: {
    fontSize: 32,
    fontWeight: 600,
    fontFamily: "Inter",
    color: "#1a1a1a"
  }
};

const contentElement: FlexElement = {
  type: "flex",
  style: {
    flexDirection: "column",
    gap: 16,
    padding: 32,
    backgroundColor: "#ffffff",
    borderRadius: 8
  },
  children: [
    titleElement,
    {
      type: "text",
      content: "Build beautiful SVG graphics from JSON",
      style: {
        fontSize: 16,
        color: "#666666"
      }
    }
  ]
};

const document: HtvgDocument = {
  meta: {
    width: 600,
    fonts: customFonts
  },
  content: contentElement
};

const result: CompileResult = compileDocument(document);

console.log(`Generated SVG: ${result.width}x${result.height}`);
if (result.warnings.length > 0) {
  console.warn("Warnings:", result.warnings);
}

Rust API

JavaScript API

CLI

TypeScript Types

Element Types

Element

BoxElement

FlexElement

TextElement

ImageElement

Style Types

BoxStyle

FlexStyle

TextStyle

ImageStyle

Primitive Types

Dimension

Spacing

BorderRadius

Color

FontWeight

Enum Types

FlexDirection

JustifyContent

AlignItems

FlexWrap

TextAlign

ObjectFit

Document Types

HtvgDocument

CompileOptions

FontSource

CompileResult

Complete Example

Build docs developers (and LLMs) love

Rust API

JavaScript API

CLI

​Element Types

​Element

​BoxElement

​FlexElement

​TextElement

​ImageElement

​Style Types

​BoxStyle

​FlexStyle

​TextStyle

​ImageStyle

​Primitive Types

​Dimension

​Spacing

​BorderRadius

​Color

​FontWeight

​Enum Types

​FlexDirection

​JustifyContent

​AlignItems

​FlexWrap

​TextAlign

​ObjectFit

​Document Types

​HtvgDocument

​CompileOptions

​FontSource

​CompileResult

​Complete Example

Build docs developers (and LLMs) love

Element Types

Element

BoxElement

FlexElement

TextElement

ImageElement

Style Types

BoxStyle

FlexStyle

TextStyle

ImageStyle

Primitive Types

Dimension

Spacing

BorderRadius

Color

FontWeight

Enum Types

FlexDirection

JustifyContent

AlignItems

FlexWrap

TextAlign

ObjectFit

Document Types

HtvgDocument

CompileOptions

FontSource

CompileResult

Complete Example