0
# Constructor and Input
1

2
Sharp instances are created using the main constructor function which accepts various input types and configuration options.
3

4
## Capabilities
5

6
### Sharp Constructor
7

8
Creates a Sharp instance from various input sources.
9

10
```javascript { .api }
11
/**
12
 * Creates a Sharp instance from various input sources
13
 * @param input - Image data source (optional)
14
 * @param options - Configuration options (optional)
15
 * @returns Sharp instance for method chaining
16
 */
17
function sharp(input?: SharpInput | SharpInput[], options?: SharpOptions): Sharp;
18

19
type SharpInput = Buffer | ArrayBuffer | Uint8Array | Uint8ClampedArray | 
20
  Int8Array | Uint16Array | Int16Array | Uint32Array | Int32Array | 
21
  Float32Array | Float64Array | string;
22
```
23

24
**Usage Examples:**
25

26
```javascript
27
// From file path
28
const image1 = sharp('input.jpg');
29

30
// From Buffer
31
const buffer = fs.readFileSync('input.png');
32
const image2 = sharp(buffer);
33

34
// Create empty instance for streaming
35
const transformer = sharp();
36

37
// With options
38
const image3 = sharp('input.tiff', {
39
  density: 300,
40
  pages: 5,
41
  failOn: 'error'
42
});
43
```
44

45
### Input Options
46

47
Configuration options for Sharp instances.
48

49
```javascript { .api }
50
interface SharpOptions {
51
  /** Auto-orient based on EXIF Orientation tag */
52
  autoOrient?: boolean;
53
  /** When to abort processing of invalid pixel data */
54
  failOn?: 'none' | 'truncated' | 'error' | 'warning';
55
  /** Pixel limit to prevent memory exhaustion */
56
  limitInputPixels?: number | boolean;
57
  /** Enable unlimited processing (removes safety features) */
58
  unlimited?: boolean;
59
  /** Use sequential rather than random access reading */
60
  sequentialRead?: boolean;
61
  /** DPI for vector images (1-100000) */
62
  density?: number;
63
  /** Ignore embedded ICC profile */
64
  ignoreIcc?: boolean;
65
  /** Number of pages to extract for multi-page input (-1 for all) */
66
  pages?: number;
67
  /** Page number to start extracting from (zero-based) */
68
  page?: number;
69
  /** Read all frames/pages of animated image */
70
  animated?: boolean;
71
  /** Raw pixel input options */
72
  raw?: CreateRaw;
73
  /** Create new image options */
74
  create?: Create;
75
  /** Create text image options */
76
  text?: CreateText;
77
  /** Join array of images options */
78
  join?: Join;
79
}
80
```
81

82
### Creating New Images
83

84
Generate new images from scratch with specified dimensions and properties.
85

86
```javascript { .api }
87
interface Create {
88
  /** Image width in pixels */
89
  width: number;
90
  /** Image height in pixels */
91
  height: number;
92
  /** Number of channels (3 for RGB, 4 for RGBA) */
93
  channels: 3 | 4;
94
  /** Background color */
95
  background: string | RGBA;
96
  /** Noise generation options */
97
  noise?: Noise;
98
  /** Page height for animated images */
99
  pageHeight?: number;
100
}
101

102
interface Noise {
103
  /** Type of noise (currently only 'gaussian') */
104
  type: 'gaussian';
105
  /** Mean of pixels in generated noise */
106
  mean?: number;
107
  /** Standard deviation of pixels in generated noise */
108
  sigma?: number;
109
}
110
```
111

112
**Usage Examples:**
113

114
```javascript
115
// Create solid color image
116
const redSquare = sharp({
117
  create: {
118
    width: 200,
119
    height: 200,
120
    channels: 4,
121
    background: { r: 255, g: 0, b: 0, alpha: 1 }
122
  }
123
});
124

125
// Create with noise
126
const noisyImage = sharp({
127
  create: {
128
    width: 100,
129
    height: 100,
130
    channels: 3,
131
    background: 'black',
132
    noise: {
133
      type: 'gaussian',
134
      mean: 128,
135
      sigma: 30
136
    }
137
  }
138
});
139
```
140

141
### Text-to-Image Generation
142

143
Create images from text using Pango markup.
144

145
```javascript { .api }
146
interface CreateText {
147
  /** Text to render as UTF-8 string (supports Pango markup) */
148
  text: string;
149
  /** Font name to render with */
150
  font?: string;
151
  /** Path to font file */
152
  fontfile?: string;
153
  /** Word-wrap width in pixels */
154
  width?: number;
155
  /** Target height in pixels (auto-fits text) */
156
  height?: number;
157
  /** Text alignment */
158
  align?: 'left' | 'centre' | 'center' | 'right';
159
  /** Apply text justification */
160
  justify?: boolean;
161
  /** Resolution for rendering (ignored if height specified) */
162
  dpi?: number;
163
  /** Enable RGBA output for color emoji */
164
  rgba?: boolean;
165
  /** Line height in points */
166
  spacing?: number;
167
  /** Word wrapping style */
168
  wrap?: 'word' | 'char' | 'word-char' | 'none';
169
}
170
```
171

172
**Usage Examples:**
173

174
```javascript
175
// Basic text image
176
const textImage = sharp({
177
  text: {
178
    text: 'Hello World',
179
    font: 'Arial',
180
    width: 400,
181
    height: 100,
182
    align: 'center',
183
    dpi: 150
184
  }
185
});
186

187
// With Pango markup
188
const styledText = sharp({
189
  text: {
190
    text: '<span foreground="red" size="x-large">Styled</span> Text',
191
    font: 'Sans',
192
    rgba: true,
193
    justify: true
194
  }
195
});
196
```
197

198
### Raw Pixel Data Input
199

200
Work with raw pixel data directly.
201

202
```javascript { .api }
203
interface CreateRaw {
204
  /** Image width in pixels */
205
  width: number;
206
  /** Image height in pixels */
207
  height: number;
208
  /** Number of channels */
209
  channels: 1 | 2 | 3 | 4;
210
  /** Raw data is already premultiplied */
211
  premultiplied?: boolean;
212
  /** Page height for animated images */
213
  pageHeight?: number;
214
}
215
```
216

217
### Joining Multiple Images
218

219
Combine array of images into single image.
220

221
```javascript { .api }
222
interface Join {
223
  /** Number of images per row */
224
  across?: number;
225
  /** Treat input as animated frames */
226
  animated?: boolean;
227
  /** Space between images in pixels */
228
  shim?: number;
229
  /** Background color */
230
  background?: string | RGBA;
231
  /** Horizontal alignment */
232
  halign?: 'left' | 'centre' | 'center' | 'right';
233
  /** Vertical alignment */
234
  valign?: 'top' | 'centre' | 'center' | 'bottom';
235
}
236
```
237

238
**Usage Examples:**
239

240
```javascript
241
// Join images in grid
242
const joined = sharp([buffer1, buffer2, buffer3, buffer4], {
243
  join: {
244
    across: 2,
245
    shim: 10,
246
    background: 'white',
247
    halign: 'center',
248
    valign: 'center'
249
  }
250
});
251

252
// Create animated sequence
253
const animated = sharp([frame1, frame2, frame3], {
254
  join: {
255
    animated: true
256
  }
257
});
258
```
259

260
### Instance Methods
261

262
Core instance methods available on all Sharp objects.
263

264
```javascript { .api }
265
/**
266
 * Create a new Sharp instance sharing the same input
267
 * @returns New Sharp instance
268
 */
269
clone(): Sharp;
270
```
271

272
**Usage Example:**
273

274
```javascript
275
const original = sharp('input.jpg');
276
const copy1 = original.clone().resize(200);
277
const copy2 = original.clone().resize(400);
278

279
// Both copies share the same input but have independent processing pipelines
280
```
281

282
## Type Definitions
283

284
```javascript { .api }
285
interface RGBA {
286
  r?: number;
287
  g?: number;
288
  b?: number;
289
  alpha?: number;
290
}
291

292
type Channels = 1 | 2 | 3 | 4;
293

294
interface Sharp {
295
  // Sharp extends Node.js Duplex stream
296
  clone(): Sharp;
297
}
298
```