ImgProcProcessorOptions

Defined in: types.ts:248

Component options

Part of props

Properties

alt?

optional alt: string

Defined in: types.ts:257

See

MDN Reference

artDirectives?

optional artDirectives: ImgProcArtDirectiveSourceProps[]

Defined in: types.ts:433

Array of art directive objects

asBackground?

optional asBackground: boolean

Defined in: types.ts:393

Enforce background mode

Only for <Image> and <Picture> components.

Default

false

backgroundPosition?

optional backgroundPosition: null | string

Defined in: types.ts:380

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%"

backgroundSize?

optional backgroundSize: null | string

Defined in: types.ts:372

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"

blurProcessor

blurProcessor: Sharp

Defined in: types.ts:321

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 })

containerAttributes?

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

Defined in: types.ts:441

Attributes for container element

crossOrigin?

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

Defined in: types.ts:459

Cross origin for preload

densities?

optional densities: number[]

Defined in: types.ts:273

x descriptors to be used in srcset

Convert to 0.5x 2x

Example

[0.5, 1, 2, 3]

enforceAspectRatio?

optional enforceAspectRatio: boolean

Defined in: types.ts:387

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

format

format: keyof ImgProcFormatOptions

Defined in: types.ts:417

Output format

Default

"webp"

formatOptions

formatOptions: ImgProcFormatOptions

Defined in: types.ts:429

Format options

jpeg png avif webp and gif are allowed.

See

sharp document

formats

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

Defined in: types.ts:423

Output formats

Last element is used as fallbak format.

Default

["avif", "webp"]

height?

optional height: number | `${number}`

Defined in: types.ts:267

Image height

layout?

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

Defined in: types.ts:345

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"

maxAge?

optional maxAge: number

Defined in: types.ts:455

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

Overrides HTTP header specification.

media?

optional media: string

Defined in: types.ts:290

See

MDN Reference

minAge?

optional minAge: number

Defined in: types.ts:450

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

Overrides HTTP header specification.

Default

1000 * 60 * 60 * 24 (1day)

objectFit?

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

Defined in: types.ts:355

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

objectPosition?

optional objectPosition: null | string

Defined in: types.ts:364

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

pictureAttributes?

optional pictureAttributes: HTMLAttributes<"picture">

Defined in: types.ts:437

Attributes for <picture> element

placeholder

placeholder: null | "blurred" | "dominantColor"

Defined in: types.ts:305

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"

placeholderColor?

optional placeholderColor: string

Defined in: types.ts:314

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

preload?

optional preload: keyof ImgProcFormatOptions

Defined in: types.ts:398

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

Only one format can be selected.

processor?

optional processor: Sharp | Sharp[]

Defined in: types.ts:405

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

profile?

optional profile: string

Defined in: types.ts:412

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.

sizes?

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

Defined in: types.ts:284

See

MDN Reference

Default

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

src?

optional src: string

Defined in: types.ts:253

Source

Local path, remote URL or data URL

tagName

tagName: keyof DefinedIntrinsicElements

Defined in: types.ts:295

Container element tagName

Default

"div"

upscale

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

Defined in: types.ts:331

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"

width?

optional width: number | `${number}`

Defined in: types.ts:263

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.

widths?

optional widths: number[]

Defined in: types.ts:279

w descriptors to be used in srcset

Convert to 1000w 2000w

Example

[1000, 1500, 2000]