0
# Image Handling
1

2
Image conversion utilities for customizing how images in DOCX documents are processed and included in the output.
3

4
## images.imgElement
5

6
Creates an image converter that generates `<img>` elements for each image in the original DOCX.
7

8
```javascript { .api }
9
function imgElement(func: (image: Image) => Promise<ImageAttributes>): ImageConverter;
10
```
11

12
### Parameters
13

14
- `func`: Function that processes an image and returns attributes for the `<img>` element
15
  - Receives an `Image` object with image data and metadata
16
  - Must return an object (or Promise of object) with HTML attributes
17
  - At minimum, should include the `src` attribute
18

19
### Returns
20

21
`ImageConverter` object that can be used with the `convertImage` option.
22

23
### Usage Examples
24

25
#### Custom Image Handler
26

27
```javascript
28
const mammoth = require("mammoth");
29

30
const options = {
31
    convertImage: mammoth.images.imgElement(function(image) {
32
        return image.readAsBase64String().then(function(imageBuffer) {
33
            return {
34
                src: "data:" + image.contentType + ";base64," + imageBuffer,
35
                alt: "Image from document"
36
            };
37
        });
38
    })
39
};
40

41
mammoth.convertToHtml({path: "document.docx"}, options);
42
```
43

44
#### Save Images to Files
45

46
```javascript
47
const fs = require("fs");
48
const path = require("path");
49

50
let imageIndex = 0;
51

52
const options = {
53
    convertImage: mammoth.images.imgElement(function(image) {
54
        imageIndex++;
55
        const extension = image.contentType.split("/")[1];
56
        const filename = `image-${imageIndex}.${extension}`;
57
        const imagePath = path.join("./images", filename);
58
        
59
        return image.readAsBuffer().then(function(imageBuffer) {
60
            return new Promise(function(resolve, reject) {
61
                fs.writeFile(imagePath, imageBuffer, function(err) {
62
                    if (err) reject(err);
63
                    else resolve({ src: `./images/${filename}` });
64
                });
65
            });
66
        });
67
    })
68
};
69
```
70

71
## images.dataUri
72

73
Default image converter that embeds images as data URIs in the HTML output.
74

75
```javascript { .api }
76
const dataUri: ImageConverter;
77
```
78

79
This is equivalent to:
80

81
```javascript
82
mammoth.images.imgElement(function(image) {
83
    return image.readAsBase64String().then(function(imageBuffer) {
84
        return {
85
            src: "data:" + image.contentType + ";base64," + imageBuffer
86
        };
87
    });
88
})
89
```
90

91
### Usage Example
92

93
```javascript
94
// This is the default behavior, so no explicit configuration needed
95
mammoth.convertToHtml({path: "document.docx"});
96

97
// Or explicitly specify:
98
const options = {
99
    convertImage: mammoth.images.dataUri
100
};
101
mammoth.convertToHtml({path: "document.docx"}, options);
102
```
103

104
## Image Object
105

106
The `Image` object passed to image converter functions provides access to image data and metadata.
107

108
```javascript { .api }
109
interface Image {
110
  contentType: string;
111
  readAsArrayBuffer(): Promise<ArrayBuffer>;
112
  readAsBase64String(): Promise<string>;
113
  readAsBuffer(): Promise<Buffer>;
114
  read(): Promise<Buffer>;
115
  read(encoding: string): Promise<string>;
116
}
117
```
118

119
### Properties and Methods
120

121
- `contentType`: MIME type of the image (e.g., "image/png", "image/jpeg")
122
- `readAsArrayBuffer()`: Read image as ArrayBuffer (browser-compatible)
123
- `readAsBase64String()`: Read image as base64-encoded string
124
- `readAsBuffer()`: Read image as Node.js Buffer (Node.js only)
125
- `read()`: Read image as Buffer (deprecated, use readAsBuffer)
126
- `read(encoding)`: Read image as string with specified encoding (deprecated)
127

128
### Usage Examples
129

130
#### Different Image Reading Methods
131

132
```javascript
133
const imageConverter = mammoth.images.imgElement(function(image) {
134
    console.log("Image type:", image.contentType);
135
    
136
    // For data URIs (most common)
137
    return image.readAsBase64String().then(function(base64) {
138
        return { src: `data:${image.contentType};base64,${base64}` };
139
    });
140
    
141
    // For saving to files
142
    // return image.readAsBuffer().then(function(buffer) {
143
    //     // Save buffer to file...
144
    //     return { src: "/path/to/saved/image.png" };
145
    // });
146
    
147
    // For browser environments
148
    // return image.readAsArrayBuffer().then(function(arrayBuffer) {
149
    //     // Process arrayBuffer...
150
    //     return { src: "..." };
151
    // });
152
});
153
```
154

155
## Image Attributes
156

157
The object returned by image converter functions becomes attributes for the generated `<img>` element.
158

159
```javascript { .api }
160
interface ImageAttributes {
161
  src: string;
162
  [key: string]: string;
163
}
164
```
165

166
### Usage Example
167

168
```javascript
169
const imageConverter = mammoth.images.imgElement(function(image) {
170
    return image.readAsBase64String().then(function(imageBuffer) {
171
        return {
172
            src: "data:" + image.contentType + ";base64," + imageBuffer,
173
            alt: "Document image",
174
            class: "document-image",
175
            width: "300",
176
            height: "200"
177
        };
178
    });
179
});
180
```
181

182
## Alt Text Handling
183

184
If alt text is found for an image in the original document, it will be automatically added to the element's attributes, even if not specified in the image converter function.
185

186
```javascript
187
// Alt text from the document is automatically preserved
188
const imageConverter = mammoth.images.imgElement(function(image) {
189
    return {
190
        src: "data:" + image.contentType + ";base64," + imageBuffer
191
        // Alt text will be added automatically if present in the document
192
    };
193
});
194
```