PHPackages                             craftsnippets/craft-image-helpers - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Image & Media](/categories/media)
4. /
5. craftsnippets/craft-image-helpers

AbandonedArchivedCraft-plugin[Image & Media](/categories/media)

craftsnippets/craft-image-helpers
=================================

Image helpers

1.0.4(5y ago)2179MITPHP

Since Apr 28Pushed 5y agoCompare

[ Source](https://github.com/craft-snippets/Craft-image-helpers)[ Packagist](https://packagist.org/packages/craftsnippets/craft-image-helpers)[ RSS](/packages/craftsnippets-craft-image-helpers/feed)WikiDiscussions master Synced 2d ago

READMEChangelog (5)Dependencies (1)Versions (6)Used By (0)

Image helpers plugin for Craft CMS 3.x
======================================

[](#image-helpers-plugin-for-craft-cms-3x)

THIS PLUGIN IS IN BETA AND SHOULD NOT BE USED IN PRODUCTION

Installation
------------

[](#installation)

```
composer require craftsnippets/craft-image-helpers

```

Usage
-----

[](#usage)

### craft.imageHelpers.picture(image, transform, htmlAttributes)

[](#craftimagehelperspictureimage-transform-htmlattributes)

This function generates `` HTML element from image asset object.

If [imager](https://plugins.craftcms.com/imager) or [imager-x](https://plugins.craftcms.com/imager-x) is installed, plugin by default will use either of them for image transforms. Otherwise, native Craft image transforms will be used. For SVG images, native craft transforms will be used instead of Imager, unless you decide otherwise in settings. This is because Imager can cause [problems if used with SVG](https://github.com/aelvan/Imager-Craft/issues/136).

First parameter of function should contain image object (not query object - so for asset field of entry, it would be `entry.assetField.one()` instead of `entry.assetField`).

Second parameter is array containing image transform settings. These settings can be identical to one used by native Craft image transforms. Transform settings are actually optional - you can use `picture()` function without providing them. This would make sense if you just wanted to make use of webp creation functionality, which is described below.

Third, optional parameter of function can contain array of HTML attributes that will be set on `` element within ``. These settings need to be in same format as accepted by [tag()](https://docs.craftcms.com/v3/dev/functions.html#tag) or [attr()](https://docs.craftcms.com/v3/dev/functions.html#attr) Twig function. More info about these functions can be found in [this article](http://craftsnippets.com/articles/using-attr-function-to-render-html-attributes-in-craft-cms).

If image is missing (image object equals `null`), placeholder will be generated based on `width` and `height` settings of transform. If either `width` or `height` are missing, placeholder will take form of square based on `width`/`height`. Placeholder is inline SVG picture and has specific CSS class which differentiates it from other non-placeholder images and allows you to style it.

Additional webp version of image will be automatically created as one of pictures element ``, assuming that:

- We didn't disabled that behaviour in plugin settings file using `useWebp` setting.
- Image is not in SVG format.
- We didn't disabled this behaviour for specific picture adding `useWebp` set to `false` in transform setting.
- Our server supports webp images.
- We don't set image transform to webp already (this would create two identical webp variants).
- Our source image is not webp, without format set in transform settings (this also would create two identical webp variants).

`` containing webp version will have `type` attribute set to `image/webp`, so browsers that do not support webp will be able to use `` with other format. That would be one that was set in transform settings, or format was not specified - source containing image in original format.

If you use imager-x (or imager), you might set additional `filenamePattern ` parameter in transform settings. This will allow you to set transfrom filename pattern. More info in [imager-x docs](https://imager-x.spacecat.ninja/configuration.html#filenamepattern-bool).

### craft.imageHelpers.pictureMedia(image, transforms, commonSettings, htmlAttributes)

[](#craftimagehelperspicturemediaimage-transforms-commonsettings-htmlattributes)

This function will generate `` element with multiple sources, each based on specific image transform and each displayed for specific media query. `transforms` array need to be structured like this:

```
{
	'(max-width: 600px)': {
		width: 100,
		height: 200,
		mode: 'crop',
	},
	'(max-width: 999px)': {
		width: 400,
		height: 500,
		mode: 'fit',
	},
	'(min-width: 1000px)': null,
}

```

This will render `` like (webp version generation disabled for simplicity sake):

```

```

Few things to note here:

- Array keys are media query strings that will used in each `` `media` attribute.
- Array values are transform settings for each source.
- If array value is set to null, this means that for specific breakpoint `` will contain only transparent pixel. This is usefull if we do not want to display picture on specific breakpoint - if we just hidden it with CSS, browser would still download it.
- Picture element has `` tag inside which serves as fallback for browsers that do not support `` (see support info on [caniuse](https://caniuse.com/#feat=picture)). First image transform will be used for fallback image.

Third parameter of function - `commonSettings` contains transform settings that are common for all transforms. It can be used to avoid setting same settings for every transform.

For example, this code:

```
{% set sources = {
    '(min-width: 1000px)': {
        width: 500,
        height: 200,
    },
    '(max-width: 999px)': {
        width: 200,
        height: 200,
    },
} %}
{% set common = {
    format: 'png',
    mode: 'stretch',
} %}

{{craft.imageHelpers.pictureMedia(glob.pole.one(), sources, common,{
    class: 'some-class',
})}}

```

Will generate `` with each source in png format and transform mode `stretch`. Note that settings of individual transforms will overwrite any conflicting settings from `commonSettings`.

Other than that, `pictureMedia()` behaves in same way as `picture()` - it can generate placeholders or webp versions of images.

### craft.imageHelpers.pictureMin(image, transforms, commonSettings, htmlAttributes)

[](#craftimagehelperspictureminimage-transforms-commonsettings-htmlattributes)

This function behaves in same way as `pictureMedia()`, except we do not use media query strings as transforms array keys. We use number of minimum screen width. Which internally will be transformed toproper breakpoints. So, for example:

```
{
	300: {
		width: 100,
		height: 200,
		mode: 'crop',
	},
	600: {
		width: 400,
		height: 500,
		mode: 'fit',
	},
}

```

This will generate `` element like this:

```

```

Note, that browser will use first `` which media query fits. So if you are on screen of width 1024px, and first source would be one with media query `(min-width: 300px)`, it would be used - even if there is other, with setting `(min-width: 600px)`. Thats why sources in this function are sorted from ones with largest min-width, to smallest.

### craft.imageHelpers.pictureMax(image, transforms, commonSettings, htmlAttributes)

[](#craftimagehelperspicturemaximage-transforms-commonsettings-htmlattributes)

Same as `pictureMin()`, except we use `max-width` media query. Sources will be sorted from smallest to largest `max-width` value.

### craft.imageHelpers.placeholder(transform)

[](#craftimagehelpersplaceholdertransform)

This function will generate placeholder based on inline SVG image. You can pass into it image transform settings array - `width` and `height` values from this array will be used.

If only width or only height is provided, image will take form of square.

Settings
--------

[](#settings)

Place these settings in `config/image.helpers.php`:

- `useWebp` - if webp version of image should automatically be generated. Default: `true`.
- `useImager` - if imager or imager-x should be used for transforms (assuming one of these plugins is installed). Default: `true`.
- `usePlaceholders` - if placeholder should be generated if image is missing (image object equals `null`). Default: `true`.
- `placeholderClass` - css class added to `` element if placeholder image is displayed. Default: `is-placeholder`.
- `useImagerForSvg` - if imager should be used also for SVG images. Default: `false`.

###  Health Score

28

—

LowBetter than 54% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity13

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity60

Established project with proven stability

 Bus Factor1

Top contributor holds 81.8% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~41 days

Total

5

Last Release

2042d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/c29f59397bc9cfcc85bb0d6350d68c0d29957c5b3bd1c9f0b7c804a1c3c5df4f?d=identicon)[piotrpog](/maintainers/piotrpog)

---

Top Contributors

[![mike-db88](https://avatars.githubusercontent.com/u/36261635?v=4)](https://github.com/mike-db88 "mike-db88 (9 commits)")[![piotrpog](https://avatars.githubusercontent.com/u/42622545?v=4)](https://github.com/piotrpog "piotrpog (2 commits)")

---

Tags

cmsCraftcraftcmscraft-pluginimage helpers

### Embed Badge

![Health badge](/badges/craftsnippets-craft-image-helpers/health.svg)

```
[![Health](https://phpackages.com/badges/craftsnippets-craft-image-helpers/health.svg)](https://phpackages.com/packages/craftsnippets-craft-image-helpers)
```

###  Alternatives

[spacecatninja/imager-x

Ninja powered image transforms.

29390.0k23](/packages/spacecatninja-imager-x)[doublesecretagency/craft-googlemaps

Maps in minutes. Powered by the Google Maps API.

1267.9k](/packages/doublesecretagency-craft-googlemaps)[nystudio107/craft-youtubeliveembed

This plugin allows you to embed a YouTube live stream and/or live chat on your webpage

163.7k](/packages/nystudio107-craft-youtubeliveembed)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)