DOCX
Images
Insert images into documents with scaling, rotation, cropping, and floating positioning
Use the image property inside a paragraph's children to embed images. Supports JPG, PNG, GIF, BMP, SVG, and more.
The data field accepts raw bytes (Uint8Array, ArrayBuffer, Buffer) or a base64 data URL such as data:image/png;base64,.... Data URLs are convenient in JSON payloads and browser environments where no file on disk is available.
Basic Image
{
"sections": [
{
"children": [
{
"paragraph": {
"children": [
{
"image": {
"type": "png",
"data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAoAAAAFoCAIAAABIUN0GAAAGFklEQVR4nO3OMQ3AQBAEseOPJwDD4rcYSwbgu/sAgOf2AwAI2g8AIGg/AICg/QAAgvYDAAjaDwAgaD8AgKD9AACC9gMACNoPACBoPwCAoP0AAIL2AwAI2g8AIGg/AICg/QAAgvYDAAjaDwAgaD8AgKD9AACC9gMACNoPACBoPwCAoP0AAIL2AwAI2g8AIGg/AICg/QAAgvYDAAjaDwAgaD8AgKD9AACC9gMACNoPACBoPwCAoP0AAIL2AwAI2g8AIGg/AICg/QAAgvYDAAjaDwAgaD8AgKD9AACC9gMACNoPACBoPwCAoP0AAIL2AwAI2g8AIGg/AICg/QAAgvYDAAjaDwAgaD8AgKD9AACC9gMACNoPACBoPwCAoP0AAIL2AwAI2g8AIGg/AICg/QAAgvYDAAjaDwAgaD8AgKD9AACC9gMACNoPACBoPwCAoP0AAIL2AwAI2g8AIGg/AICg/QAAgvYDAAjaDwAgaD8AgKD9AACC9gMACNoPACBoPwCAoP0AAIL2AwAI2g8AIGg/AICg/QAAgvYDAAjaDwAgaD8AgKD9AACC9gMACNoPACBoPwCAoP0AAIL2AwAI2g8AIGg/AICg/QAAgvYDAAjaDwAgaD8AgKD9AACC9gMACNoPACBoPwCAoP0AAIL2AwAI2g8AIGg/AICg/QAAgvYDAAjaDwAgaD8AgKD9AACC9gMACNoPACBoPwCAoP0AAIL2AwAI2g8AIGg/AICg/QAAgvYDAAjaDwAgaD8AgKD9AACC9gMACNoPACBoPwCAoP0AAIL2AwAI2g8AIGg/AICg/QAAgvYDAAjaDwAgaD8AgKD9AACC9gMACNoPACBoPwCAoP0AAIL2AwAI2g8AIGg/AICg/QAAgvYDAAjaDwAgaD8AgKD9AACC9gMACNoPACBoPwCAoP0AAIL2AwAI2g8AIGg/AICg/QAAgvYDAAjaDwAgaD8AgKD9AACC9gMACNoPACBoPwCAoP0AAIL2AwAI2g8AIGg/AICg/QAAgvYDAAjaDwAgaD8AgKD9AACC9gMACNoPACBoPwCAoP0AAIL2AwAI2g8AIGg/AICg/QAAgvYDAAjaDwAgaD8AgKD9AACC9gMACNoPACBoPwCAoP0AAIL2AwAI2g8AIGg/AICg/QAAgvYDAAjaDwAgaD8AgKD9AACC9gMACNoPACBoPwCAoP0AAIL2AwAI2g8AIGg/AICg/QAAgvYDAAjaDwAgaD8AgKD9AACC9gMACNoPACBoPwCAoP0AAIL2AwAI2g8AIGg/AICg/QAAgvYDAAjaDwAgaD8AgKD9AACC9gMACNoPACBoPwCAoP0AAIL2AwAI2g8AIGg/AICg/QAAgvYDAAjaDwAgaD8AgKD9AACC9gMACNoPACBoPwCAoP0AAIL2AwAI2g8AIGg/AICg/QAAgvYDAAjaDwAgaD8AgKD9AACC9gMACNoPACBoPwCAoP0AAIL2AwAI2g8AIGg/AICg/QAAgvYDAAjaDwAgaD8AgKD9AACC9gMACNoPACBoPwCAoP0AAIL2AwAI2g8AIGg/AICg/QAAgvYDAAjaDwAgaD8AgKD9AACC9gMACNoPACBoPwCAoP0AAIL2AwAI2g8AIGg/AICg/QAAgvYDAAjaDwAgaD8AgKD9AACC9gMACNoPACBoPwCAoP0AAIL2AwAI2g8AIGg/AICg/QAAgvYDAAjaDwAgaD8AgKD9AACC9gMACNoPACBoPwCAoP0AAIL2AwAI2g8AIGg/AICg/QAAgvYDAAjaDwAgaD8AgKD9AACC9gMACNoPACBoPwCAoP0AAIL2AwAI2g8AIGg/AICg/QAAgvYDAAjaDwAgaD8AgKD9AACC9gMACNoPACBoPwCAoP0AAIL2AwAI2g8AIGg/AICg/QAAgvYDAAjaDwAgaD8AgKD9AACC9gMACNoPACBoPwCAoP0AAIL2AwAI2g8AIGg/AICg/QAAgvYDAAjaDwAgaD8AgKD9AACC9gMACNoPACBoPwCAoP0AAIL2AwAI2g8AIGg/AICg/QAAgvYDAAjaDwAgaD8AgKD9AACC9gMACNoPACBoPwCAnB/XZ/UJD/Bi1wAAAABJRU5ErkJggg==",
"transformation": { "width": "5.3cm", "height": "4.0cm" }
}
}
]
}
}
]
}
]
}
import { readFileSync } from "node:fs";
import { generateDocument } from "@office-open/docx";
const imageBuffer = readFileSync("photo.png");
const buffer = await generateDocument({
sections: [
{
children: [
{
paragraph: {
children: [
{
image: {
type: "png",
data: imageBuffer,
transformation: { width: "5.3cm", height: "4.0cm" },
},
},
],
},
},
],
},
],
});
Transformations
Control size, rotation, and flip:
{
"sections": [
{
"children": [
{
"paragraph": {
"children": [
{
"image": {
"type": "jpg",
"data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=",
"transformation": {
"width": "7.9cm",
"height": "5.3cm",
"rotation": 45,
"flip": { "horizontal": true }
}
}
}
]
}
}
]
}
]
}
import { generateDocument } from "@office-open/docx";
const buffer = await generateDocument({
sections: [
{
children: [
{
paragraph: {
children: [
{
image: {
type: "jpg",
data: imageBuffer,
transformation: {
width: "7.9cm",
height: "5.3cm",
rotation: 45, // Rotate 45 degrees
flip: { horizontal: true }, // Flip horizontally
},
},
},
],
},
},
],
},
],
});
Cropping
Use srcRect to crop the source image:
{
"sections": [
{
"children": [
{
"paragraph": {
"children": [
{
"image": {
"type": "png",
"data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=",
"transformation": { "width": "5.3cm", "height": "5.3cm" },
"srcRect": { "left": 1000, "top": 1000, "right": 1000, "bottom": 1000 }
}
}
]
}
}
]
}
]
}
import { generateDocument } from "@office-open/docx";
const buffer = await generateDocument({
sections: [
{
children: [
{
paragraph: {
children: [
{
image: {
type: "png",
data: imageBuffer,
transformation: { width: "5.3cm", height: "5.3cm" },
srcRect: {
left: 1000, // Crop left edge (in EMUs)
top: 1000, // Crop top edge (in EMUs)
right: 1000, // Crop right edge (in EMUs)
bottom: 1000, // Crop bottom edge (in EMUs)
},
},
},
],
},
},
],
},
],
});
Floating Images
Use the floating option to position images with text wrapping:
{
"sections": [
{
"children": [
{
"paragraph": {
"children": [
{
"image": {
"type": "png",
"data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=",
"transformation": { "width": "4.0cm", "height": "4.0cm" },
"floating": {
"horizontalPosition": { "offset": 720000 },
"verticalPosition": { "offset": 720000 },
"wrap": { "type": "square" }
}
}
}
]
}
}
]
}
]
}
import { generateDocument } from "@office-open/docx";
const buffer = await generateDocument({
sections: [
{
children: [
{
paragraph: {
children: [
{
image: {
type: "png",
data: imageBuffer,
transformation: { width: "4.0cm", height: "4.0cm" },
floating: {
horizontalPosition: {
offset: 720000, // Position from page left (in EMUs)
},
verticalPosition: {
offset: 720000, // Position from page top (in EMUs)
},
wrap: {
type: "square", // Text wraps around the image
},
},
},
},
],
},
},
],
},
],
});
Image Effects (Blip Effects)
Apply adjustment effects directly to images using blipEffects:
{
"sections": [
{
"children": [
{
"paragraph": {
"children": [
{
"image": {
"type": "jpg",
"data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=",
"transformation": { "width": "4.0cm", "height": "4.0cm" },
"blipEffects": { "luminance": { "bright": 30, "contrast": -20 } }
}
}
]
}
}
]
}
]
}
import { generateDocument } from "@office-open/docx";
const buffer = await generateDocument({
sections: [
{
children: [
{
paragraph: {
children: [
{
image: {
type: "jpg",
data: imageBuffer,
transformation: { width: "4.0cm", height: "4.0cm" },
blipEffects: {
// Brightness +30%, Contrast -20%
luminance: { bright: 30, contrast: -20 },
},
},
},
],
},
},
],
},
],
});
Available Blip Effects
| Property | Type | Description |
|---|---|---|
grayscale | boolean | Convert to grayscale |
luminance | { bright?, contrast? } | Adjust brightness/contrast (%) |
hsl | { hue?, saturation?, luminance? } | Adjust HSL color values |
tint | { hue?, amount? } | Apply color tint |
duotone | { color1, color2 } | Two-color tone mapping |
biLevel | { threshold } | Black & white threshold (0-100) |
Grayscale
{
"sections": [
{
"children": [
{
"paragraph": {
"children": [
{
"image": {
"type": "jpg",
"data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=",
"transformation": { "width": "4.0cm", "height": "4.0cm" },
"blipEffects": { "grayscale": true }
}
}
]
}
}
]
}
]
}
import { generateDocument } from "@office-open/docx";
const buffer = await generateDocument({
sections: [
{
children: [
{
paragraph: {
children: [
{
image: {
type: "jpg",
data: imageBuffer,
transformation: { width: "4.0cm", height: "4.0cm" },
blipEffects: { grayscale: true },
},
},
],
},
},
],
},
],
});
Duotone
{
"sections": [
{
"children": [
{
"paragraph": {
"children": [
{
"image": {
"type": "jpg",
"data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=",
"transformation": { "width": "4.0cm", "height": "4.0cm" },
"blipEffects": {
"duotone": { "color1": { "value": "002060" }, "color2": { "value": "D0CECE" } }
}
}
}
]
}
}
]
}
]
}
import { generateDocument } from "@office-open/docx";
const buffer = await generateDocument({
sections: [
{
children: [
{
paragraph: {
children: [
{
image: {
type: "jpg",
data: imageBuffer,
transformation: { width: "4.0cm", height: "4.0cm" },
blipEffects: {
duotone: {
color1: { value: "002060" },
color2: { value: "D0CECE" },
},
},
},
},
],
},
},
],
},
],
});
Tint
{
"sections": [
{
"children": [
{
"paragraph": {
"children": [
{
"image": {
"type": "jpg",
"data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=",
"transformation": { "width": "4.0cm", "height": "4.0cm" },
"blipEffects": { "tint": { "hue": 6000000, "amount": 40 } }
}
}
]
}
}
]
}
]
}
import { generateDocument } from "@office-open/docx";
const buffer = await generateDocument({
sections: [
{
children: [
{
paragraph: {
children: [
{
image: {
type: "jpg",
data: imageBuffer,
transformation: { width: "4.0cm", height: "4.0cm" },
blipEffects: {
tint: { hue: 6000000, amount: 40 },
},
},
},
],
},
},
],
},
],
});
SVG with Fallback
{
"sections": [
{
"children": [
{
"paragraph": {
"children": [
{
"image": {
"type": "svg",
"data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=",
"transformation": { "width": "5.3cm", "height": "5.3cm" },
"fallback": {
"type": "png",
"data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII="
}
}
}
]
}
}
]
}
]
}
import { generateDocument } from "@office-open/docx";
const buffer = await generateDocument({
sections: [
{
children: [
{
paragraph: {
children: [
{
image: {
type: "svg",
data: svgBuffer,
transformation: { width: "5.3cm", height: "5.3cm" },
fallback: {
type: "png",
data: pngBuffer,
},
},
},
],
},
},
],
},
],
});