Skip to main content

Images

Learn how to insert images into Excel with xlmake.

Basic Usage​

import { xlmake } from "xlmake";
import { readFileSync } from "fs";

const logoBuffer = readFileSync("./logo.png");

const output = await xlmake()
  .sheet("Report")
  .image({
    source: logoBuffer,
    width: 150,
    height: 75,
  })
  .getNode();

ImageOptions​

.image({
  source: Buffer | string,  // Image data or file path
  width?: number,           // Width (pixels)
  height?: number,          // Height (pixels)
  row?: number,             // Row position (0-indexed)
  col?: number,             // Column position (0-indexed)
})

Specifying source​

import { readFileSync } from "fs";

const imageBuffer = readFileSync("./image.png");

.image({
  source: imageBuffer,
  width: 200,
  height: 100,
})

Using File Path (Node.js only)​

.image({
  source: "./image.png",
  width: 200,
  height: 100,
})

Using URL (Browser & Node.js)​

.image({
  source: "https://example.com/image.png",
  width: 200,
  height: 100,
})

Browser Usage​

In browser environments, you can insert images using URL.

import { xlmake } from "xlmake";

const output = await xlmake()
  .sheet("Report")
  .image({
    source: "https://example.com/logo.png",
    width: 150,
    height: 75,
  })
  .getBrowser();

await output.download("report.xlsx");
note

File path specification is only available in Node.js environment. Use URL or Buffer in browser environments.

Specifying Size​

Image size is specified in pixels.

.image({
  source: imageBuffer,
  width: 300,   // 300 pixels wide
  height: 150,  // 150 pixels tall
})

Specifying Position​

Use row and col to specify placement position (starting from 0).

.image({
  source: imageBuffer,
  width: 200,
  height: 100,
  row: 5,   // Row 6
  col: 2,   // Column C
})

Combining with Text and Tables​

const output = await xlmake()
  .sheet("Report")
  .text({ value: "Monthly Report", style: { bold: true, fontSize: 16 } })
  .space(1)
  .image({
    source: logoBuffer,
    width: 150,
    height: 75,
  })
  .space(2)
  .table({
    preset: "basic",
    columns: [...],
    data: [...],
  })
  .getNode();

Complete Example​

import { xlmake } from "xlmake";
import { readFileSync } from "fs";

const logoBuffer = readFileSync("./company-logo.png");
const chartBuffer = readFileSync("./sales-chart.png");

const output = await xlmake()
  .sheet("Report")
  // Header section
  .text({ value: "Sample Corporation", style: { bold: true, fontSize: 18 } })
  .space(1)
  .image({
    source: logoBuffer,
    width: 120,
    height: 60,
  })
  .space(2)
  // Data table
  .text({ value: "Sales Data", style: { bold: true, fontSize: 14 } })
  .space(1)
  .table({
    preset: "basic",
    columns: [
      { key: "month", label: "Month" },
      { key: "sales", label: "Sales" },
    ],
    data: [
      { month: "January", sales: 1000000 },
      { month: "February", sales: 1200000 },
      { month: "March", sales: 1100000 },
    ],
  })
  .space(2)
  // Chart image
  .text({ value: "Sales Trend Chart", style: { bold: true, fontSize: 14 } })
  .space(1)
  .image({
    source: chartBuffer,
    width: 400,
    height: 250,
  })
  .getNode();

await output.saveToFile("report-with-images.xlsx");