Element Types

HTVG provides four fundamental element types that form the building blocks of any document. Each element type has a specific role and set of style properties.

Element Overview

Box

Block container element for simple layouts

Flex

Flexbox container with full CSS Flexbox support

Text

Text leaf element with automatic line wrapping

Image

Image element with intrinsic dimensions

Box Element

The box element is a basic block container. It’s the simplest container type, ideal for simple layouts without flex properties.

Schema

{
  type: "box",
  style?: BoxStyle,
  children?: Element[]
}

Example

Basic Box
With Children

{
  "type": "box",
  "style": {
    "width": 200,
    "height": 100,
    "backgroundColor": "#2563eb",
    "borderRadius": 8
  },
  "children": []
}

{
  "type": "box",
  "style": {
    "padding": 20,
    "backgroundColor": "#ffffff",
    "borderWidth": 1,
    "borderColor": "#e0e0e0"
  },
  "children": [
    {
      "type": "text",
      "content": "Box content",
      "style": { "fontSize": 16 }
    }
  ]
}

Box Style Properties

display

string

default:"block"

Display mode: "block", "flex", or "none"

width

number | string

Width in pixels (number) or percentage (string like "50%")

height

number | string

Height in pixels (number) or percentage (string like "50%")

minWidth

number | string

Minimum width constraint

maxWidth

number | string

Maximum width constraint

minHeight

number | string

Minimum height constraint

maxHeight

number | string

Maximum height constraint

margin

number | string

default:"0"

Margin spacing. Can be:

Single number: 20 (all sides)
Space-separated: "10 20" (vertical horizontal)
Four values: "10 20 30 40" (top right bottom left)

padding

number | string

default:"0"

Padding spacing with same syntax as margin

backgroundColor

string

Background color (hex, rgb, rgba, or named color)

borderWidth

number

default:"0"

Border width in pixels

borderColor

string

Border color

borderRadius

number | string

default:"0"

Corner radius. Can be:

Single number: 8 (all corners)
Four values: "8 8 0 0" (top-left top-right bottom-right bottom-left)

opacity

number

default:"1"

Opacity from 0 (transparent) to 1 (opaque)

Flex Element

The flex element is a flexbox container supporting full CSS Flexbox layout. It’s the most powerful container type for complex layouts.

Schema

{
  type: "flex",
  style?: FlexStyle,
  children?: Element[]
}

Example

Column Layout
Centered Content
Badge Row

{
  "type": "flex",
  "style": {
    "flexDirection": "column",
    "gap": 12,
    "padding": 20,
    "backgroundColor": "#f8f9fa"
  },
  "children": [
    {
      "type": "text",
      "content": "Item 1",
      "style": { "fontSize": 16 }
    },
    {
      "type": "text",
      "content": "Item 2",
      "style": { "fontSize": 16 }
    }
  ]
}

{
  "type": "flex",
  "style": {
    "flexDirection": "column",
    "justifyContent": "center",
    "alignItems": "center",
    "width": 400,
    "height": 300,
    "backgroundColor": "#ffffff"
  },
  "children": [
    {
      "type": "text",
      "content": "Centered Text",
      "style": { "fontSize": 24, "fontWeight": "bold" }
    }
  ]
}

{
  "type": "flex",
  "style": {
    "flexDirection": "row",
    "gap": 10,
    "flexWrap": "wrap"
  },
  "children": [
    {
      "type": "flex",
      "style": {
        "backgroundColor": "#22c55e",
        "borderRadius": 16,
        "padding": "6 14"
      },
      "children": [
        {
          "type": "text",
          "content": "Passing",
          "style": { "fontSize": 13, "fontWeight": 600, "color": "#ffffff" }
        }
      ]
    }
  ]
}

Flex Style Properties

Flex elements inherit all Box style properties, plus additional flex-specific properties:

flexDirection

string

default:"row"

Flex direction: "row", "column", "row-reverse", "column-reverse"

justifyContent

string

default:"flex-start"

Main axis alignment:

"flex-start" - Align to start
"flex-end" - Align to end
"center" - Center items
"space-between" - Space between items
"space-around" - Space around items
"space-evenly" - Even spacing

alignItems

string

default:"stretch"

Cross axis alignment:

"flex-start" - Align to start
"flex-end" - Align to end
"center" - Center items
"stretch" - Stretch to fill
"baseline" - Align baselines

gap

number

default:"0"

Gap between flex items in pixels

flexWrap

string

default:"nowrap"

Wrapping behavior: "nowrap" or "wrap"

All dimension properties (width, height, margin, padding, backgroundColor, borderWidth, borderColor, borderRadius, opacity) work the same as in Box elements.

Text Element

The text element is a leaf element for rendering text with automatic line wrapping and proper text shaping via Parley.

Schema

{
  type: "text",
  content: string,
  style?: TextStyle
}

Example

Basic Text
Paragraph
Centered

{
  "type": "text",
  "content": "Hello, HTVG!",
  "style": {
    "fontSize": 24,
    "fontWeight": "bold",
    "color": "#1a1a1a"
  }
}

{
  "type": "text",
  "content": "This is a self-contained document rendered to SVG. Text automatically wraps based on the available width.",
  "style": {
    "fontSize": 16,
    "lineHeight": 1.5,
    "color": "#666666"
  }
}

{
  "type": "text",
  "content": "Centered Text",
  "style": {
    "fontSize": 20,
    "fontWeight": 700,
    "textAlign": "center",
    "color": "#1a1a1a"
  }
}

Text Style Properties

fontFamily

string

default:"sans-serif"

Font family name

fontSize

number

default:"16"

Font size in pixels

fontWeight

number | string

default:"400"

Font weight: number (100-900) or keyword ("normal" = 400, "bold" = 700)

lineHeight

number

default:"1.2"

Line height as a multiplier of font size

textAlign

string

default:"left"

Text alignment: "left", "center", "right", "justify"

color

string

default:"#000000"

Text color (hex, rgb, rgba, or named)

letterSpacing

number

default:"0"

Letter spacing in pixels

textRendering

string

default:"text"

Rendering mode:

"text" - Render as SVG <text> element
"vector" - Render as vector paths (future feature)

flexGrow

number

default:"0"

Flex grow factor when inside a flex container

flexShrink

number

default:"1"

Flex shrink factor when inside a flex container

Text elements automatically wrap based on the available width calculated by the layout engine. You don’t need to manually insert line breaks.

Image Element

The image element renders images with intrinsic dimensions. Images must provide width and height.

Schema

{
  type: "image",
  src: string,
  width: number,
  height: number,
  style?: ImageStyle
}

Example

Basic Image
Rounded Image
Constrained

{
  "type": "image",
  "src": "data:image/png;base64,iVBORw0KGg...",
  "width": 100,
  "height": 100,
  "style": {}
}

{
  "type": "image",
  "src": "https://example.com/image.png",
  "width": 200,
  "height": 150,
  "style": {
    "borderRadius": 12,
    "objectFit": "cover"
  }
}

{
  "type": "image",
  "src": "data:image/jpeg;base64,...",
  "width": 800,
  "height": 600,
  "style": {
    "maxWidth": 400,
    "objectFit": "contain"
  }
}

Image Style Properties

width

number | string

Override intrinsic width

height

number | string

Override intrinsic height

minWidth

number | string

Minimum width constraint

maxWidth

number | string

Maximum width constraint

minHeight

number | string

Minimum height constraint

maxHeight

number | string

Maximum height constraint

margin

number | string

default:"0"

Margin spacing (same syntax as Box)

objectFit

string

default:"contain"

Image fit mode:

"contain" - Scale to fit, preserving aspect ratio
"cover" - Scale to cover, preserving aspect ratio
"fill" - Stretch to fill

borderRadius

number | string

default:"0"

Corner radius for clipping

opacity

number

default:"1"

Image opacity (0-1)

flexGrow

number

default:"0"

Flex grow factor when inside a flex container

flexShrink

number

default:"1"

Flex shrink factor when inside a flex container

The src field accepts both data URIs (data:image/png;base64,...) and external URLs. For self-contained SVG output, use data URIs.

Type Definitions

The complete type definitions are available in the source code at crates/htvg-core/src/element.rs. Here’s the core enum:

pub enum Element {
    Box {
        style: BoxStyle,
        children: Vec<Element>,
    },
    Flex {
        style: FlexStyle,
        children: Vec<Element>,
    },
    Text {
        content: String,
        style: TextStyle,
    },
    Image {
        src: String,
        width: f32,
        height: f32,
        style: ImageStyle,
    },
}

Style Properties

Complete style property reference

Layout Engine

How Taffy computes layout

Get Started

Core Concepts

Guides

Element Types

Element Overview

Box

Flex

Text

Image

Box Element

Schema

Example

Box Style Properties

Flex Element

Schema

Example

Flex Style Properties

Text Element

Schema

Example

Text Style Properties

Image Element

Schema

Example

Image Style Properties

Type Definitions

Style Properties

Layout Engine

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

​Element Overview

Box

Flex

Text

Image

​Box Element

​Schema

​Example

​Box Style Properties

​Flex Element

​Schema

​Example

​Flex Style Properties

​Text Element

​Schema

​Example

​Text Style Properties

​Image Element

​Schema

​Example

​Image Style Properties

​Type Definitions

​Related Topics

Style Properties

Layout Engine

Build docs developers (and LLMs) love

Element Overview

Box Element

Schema

Example

Box Style Properties

Flex Element

Schema

Example

Flex Style Properties

Text Element

Schema

Example

Text Style Properties

Image Element

Schema

Example

Image Style Properties

Type Definitions

Related Topics