ImgProcProcessorOptions

Component options

Part of props

Properties

alt?

optional alt: string

See

MDN Reference

Defined in

src/types.ts:257

artDirectives?

optional artDirectives: ImgProcArtDirectiveSourceProps[]

Array of art directive objects

Defined in

src/types.ts:433

asBackground?

optional asBackground: boolean

Enforce background mode

Only for <Image> and <Picture> components.

Default

false

Defined in

src/types.ts:393

backgroundPosition?

optional backgroundPosition: null | string

Set CSS property background-position to the container element or the blurred image

For <Background> component, apply to the container element.
If <Image> or <Picture> component and the placeholder is blurred, apply to the <picture> and <img> elements.

See

MDN Reference: background-position

Default

"50% 50%"

Defined in

src/types.ts:380

backgroundSize?

optional backgroundSize: null | string

Set CSS property background-size to the container element or the blurred image

For <Background> component, apply to the container element.
If <Image> or <Picture> component and the placeholder is blurred, apply to the <picture> and <img> elements.

See

MDN Reference: background-size

Default

"cover"

Defined in

src/types.ts:372

blurProcessor

blurProcessor: Sharp

Sharp instance to generate blurred images

Note that blurred images are written to the inline CSS (and cache database) as Base64.
Must include output option. ( .webp() .avif() etc.)

Defult

sharp().resize(20).webp({ quality: 1 })

Defined in

src/types.ts:321

containerAttributes?

optional containerAttributes: Record<string, unknown> | HTMLAttributes<"div"> | HTMLAttributes<"a">

Attributes for container element

Defined in

src/types.ts:441

crossOrigin?

optional crossOrigin: null | "" | "anonymous" | "use-credentials"

Cross origin for preload

Defined in

src/types.ts:459

densities?

optional densities: number[]

x descriptors to be used in srcset

Convert to 0.5x 2x

Example

[0.5, 1, 2, 3]

Defined in

src/types.ts:273

enforceAspectRatio?

optional enforceAspectRatio: boolean

Set CSS property aspect-ratio to the container element based on width and height

Only for <Background> component and background mode.
If width and/or height are not set as properties, the values resolved within the component are used.

See

MDN Reference: aspect-ratio

Defined in

src/types.ts:387

format

format: keyof ImgProcFormatOptions

Output format

Default

"webp"

Defined in

src/types.ts:417

formatOptions

formatOptions: ImgProcFormatOptions

Format options

jpeg png avif webp and gif are allowed.

See

sharp document

Defined in

src/types.ts:429

formats

formats: [keyof ImgProcFormatOptions, ...(keyof ImgProcFormatOptions)[]]

Output formats

Last element is used as fallbak format.

Default

["avif", "webp"]

Defined in

src/types.ts:423

height?

optional height: number | `${number}`

Image height

Defined in

src/types.ts:267

layout?

optional layout: null | "constrained" | "fixed" | "fullWidth" | "fill"

Specify the layout of the image

Apply by adding the global class globalClassNames.layout[layout] to the <picture> and <img> elements.
If set to constrained or fixed, the CSS property width of the <img> element is set to the resolved value as scoped style.
The <GlobalStyles> component sets the styles as follows:
- constrained: max-width: 100%; height: auto;
- fixed: N/A
- fullWidth: width: 100%; height: auto;
- fill: width: 100%; height: 100%;
Styles can also be defined manually instead of <GlobalStyles> using the generated classes.

See

layout (Gatsby Image plugin)

Default

"constrained"

Defined in

src/types.ts:345

maxAge?

optional maxAge: number

Maximum value of cache expiration period for remote files (milliseconds)

Overrides HTTP header specification.

Defined in

src/types.ts:455

media?

optional media: string

See

MDN Reference

Defined in

src/types.ts:290

minAge?

optional minAge: number

Minimum value of cache expiration period for remote files (milliseconds)

Overrides HTTP header specification.

Default

1000 * 60 * 60 * 24 (1day)

Defined in

src/types.ts:450

objectFit?

optional objectFit: null | "none" | "fill" | "contain" | "cover" | "scale-down"

Set CSS property object-fit to the <img> element

Apply by adding the global class globalClassNames.objectFit[objectFit] to the <img> element.
The object-fit is set to this value by the <GlobalStyles> component.
Styles can also be defined manually instead of <GlobalStyles> using the generated classes.
If a default value is required, specify it in the global style.

See

MDN Reference: object-fit

Default

null

Defined in

src/types.ts:355

objectPosition?

optional objectPosition: null | string

Set CSS property object-position to the <img> element

If placeholder is blurred and backgroundPosition is null, the value uses for background-position property for blurred image.
- If both objectPosition and backgroundPosition are null, then 50% 50% is used.
If a default value is required, specify it in the global style.

See

MDN Reference: object-position

Default

null

Defined in

src/types.ts:364

pictureAttributes?

optional pictureAttributes: HTMLAttributes<"picture">

Attributes for <picture> element

Defined in

src/types.ts:437

placeholder

placeholder: null | "blurred" | "dominantColor"

Placeholder

dominantColor : Use sharp().stats().dominant or the value of dominantColor option
- Use for background-color in BackgroundImage component.
blurred : Use blurred image generated by blurProcessor
- Unavailable for BackgroundImage component.
null : Disable placeholder

Default

"blurred"

Defined in

src/types.ts:305

placeholderColor?

optional placeholderColor: string

Background color

If set, use for placeholder instead of dominant color.
Only works with placeholder option is dominantColor.
Written to the CSS directly.
Can also use var(--foo).

See

MDN Reference: color

Defined in

src/types.ts:314

preload?

optional preload: keyof ImgProcFormatOptions

Output <link rel="preload" ... >

Only one format can be selected.

Defined in

src/types.ts:398

processor?

optional processor: Sharp | Sharp[]

Sharp instance to process the image

Do not use output options except the options about Exif/ICC Profile/Metadata.

Example

sharp().grayscale().blur()

See

sharp documentation

Defined in

src/types.ts:405

profile?

optional profile: string

Identifier of image processing profile for caching

Not necessary for usual.
If not set, hash of sharp().options will be used to identify the processing profile.
If set, this value is used instead of the hash. This is faster than calculating the hash each time.

Defined in

src/types.ts:412

sizes?

optional sizes: string | (resolvedWidths, resolvedDensities) => string

See

MDN Reference

Default

(min-width: ${widths.at(-1)}px) ${widths.at(-1)}px, 100vw

Defined in

src/types.ts:284

src?

optional src: string

Source

Local path, remote URL or data URL

Defined in

src/types.ts:253

tagName

tagName: keyof DefinedIntrinsicElements

Container element tagName

Default

"div"

Defined in

src/types.ts:295

upscale

upscale: "never" | "always" | "original"

How to handle the value of widths/densities that are larger than the image.

always: Upscale the image to address all values.
never: Ignore values larger than the original image size.
- If image real width is 2500, width prop is 1000 and densities prop is [1, 2, 3], densities set to [1, 2].
original: Add the original image size as the largest value.
- If image real width is 2500, width prop is 1000 and densities prop is [1, 2, 3], densities set to [1, 2, 2.5].

Default

"never"

Defined in

src/types.ts:331

width?

optional width: number | `${number}`

Image width

If densities option is used, this value is used as the value of 1x.
If not set and densities option is used, the source image is used as the maximum density.

Defined in

src/types.ts:263

widths?

optional widths: number[]

w descriptors to be used in srcset

Convert to 1000w 2000w

Example

[1000, 1500, 2000]

Defined in

src/types.ts:279