PHPackages                             carbon/image - 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. [Utility & Helpers](/categories/utility)
4. /
5. carbon/image

ActiveNeos-carbon[Utility & Helpers](/categories/utility)

carbon/image
============

Image helper for Neos CMS

4.6.0(10mo ago)339.6k↓50%5GPL-3.0-or-laterCSS

Since Jul 31Pushed 10mo ago2 watchersCompare

[ Source](https://github.com/CarbonPackages/Carbon.Image)[ Packagist](https://packagist.org/packages/carbon/image)[ Fund](https://www.paypal.me/Jonnitto/20eur)[ GitHub Sponsors](https://github.com/jonnitto)[ RSS](/packages/carbon-image/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (4)Versions (51)Used By (5)

[![Latest stable version](https://camo.githubusercontent.com/c4591c0d7334c671568a0773231ce011cf2a2b175a3fc0dccf565aa4ed0d40e0/68747470733a2f2f706f7365722e707567782e6f72672f636172626f6e2f696d6167652f762f737461626c65)](https://packagist.org/packages/carbon/image) [![Total downloads](https://camo.githubusercontent.com/8298d7fb6fc5d15619ad509ff3ae2832bcce7e194e39a2bb5dc1685935d74951/68747470733a2f2f706f7365722e707567782e6f72672f636172626f6e2f696d6167652f646f776e6c6f616473)](https://packagist.org/packages/carbon/image) [![License](https://camo.githubusercontent.com/b8d6342cdf40cc25c75cd4d89984cef8059efab4c5bd5d3320a76eda0eee8e9c/68747470733a2f2f706f7365722e707567782e6f72672f636172626f6e2f696d6167652f6c6963656e7365)](https://packagist.org/packages/carbon/image) [![GitHub forks](https://camo.githubusercontent.com/de8c938169879e650128e6739f8797f0e708c38bec257f41d3ebb8dad504151a/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f666f726b732f436172626f6e5061636b616765732f436172626f6e2e496d6167652e7376673f7374796c653d736f6369616c266c6162656c3d466f726b)](https://github.com/CarbonPackages/Carbon.Image/fork) [![GitHub stars](https://camo.githubusercontent.com/cf7866c323194223efe0282b3ae5f1865e7d2613e73548ba24eeaa1fb47410b5/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f73746172732f436172626f6e5061636b616765732f436172626f6e2e496d6167652e7376673f7374796c653d736f6369616c266c6162656c3d5374617273)](https://github.com/CarbonPackages/Carbon.Image/stargazers) [![GitHub watchers](https://camo.githubusercontent.com/c141dbe465901cec60e17d7823fe6d8d63ddbdae564efc011be9e56bf345f3d2/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f77617463686572732f436172626f6e5061636b616765732f436172626f6e2e496d6167652e7376673f7374796c653d736f6369616c266c6162656c3d5761746368)](https://github.com/CarbonPackages/Carbon.Image/subscription)

Carbon.Image Package for Neos CMS
=================================

[](#carbonimage-package-for-neos-cms)

This package provides some fusion helper for images based on [Sitegeist.Kaleidoscope](https://github.com/sitegeist/Sitegeist.Kaleidoscope); you have to create the node type for yourself. Here you see an example of an implementation: [Jonnitto.ImagesInARow](https://github.com/jonnitto/Jonnitto.ImagesInARow)

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

[](#installation)

Most of the time you have to make small adjustments to a package (e.g. [configuration](Configuration) in `Settings.yaml`). Because of that, it is important to add the corresponding package to the composer from your theme package. Mostly this is the site packages located under `Packages/Sites/`. To install it correctly go to your theme package (e.g.`Packages/Sites/Foo.Bar`) and run following command:

```
composer require carbon/image --no-update
```

The `--no-update` command prevent the automatic update of the dependencies. After the package was added to your theme `composer.json`, go back to the root of the Neos installation and run `composer update`. Et voilà! Your desired package is now installed correctly.

Abstract node types
-------------------

[](#abstract-node-types)

Below a list of which abstract node types (a.k.a. mixins) you can use in your projects:

NameDescription[`Carbon.Image:Image`](NodeTypes/Image.yaml)Creates the property `image`, the label and the icon[`Carbon.Image:AlternativeText`](NodeTypes/AlternativeText.yaml)Creates an input field in the inspector for the property `alternativeText`[`Carbon.Image:BackendLabel`](NodeTypes/BackendLabel.yaml)Create the label in the backend based on the properties `title`, `alternativeText`, `caption` and `text`[`Carbon.Image:Lightbox`](NodeTypes/Lightbox.yaml)Creates a checkbox in the inspector for the property `lightbox`[`Carbon.Image:Link`](NodeTypes/Link.yaml)Creates a link editor in the inspector for the property `link`[`Carbon.Image:Title`](NodeTypes/Title.yaml)Creates an input field in the inspector for the property `title`[`Carbon.Image:Group`](NodeTypes/Group.yaml)This is a mixins to create the group `image` in the inspector. This is used by all mixons, except by [`Carbon.Image:BackendLabel`](NodeTypes/BackendLabel.yaml).Fusion
------

[](#fusion)

### Presentational components

[](#presentational-components)

#### [`Carbon.Image:Component.Presentation.Image`](Resources/Private/Fusion/Component/Presentation/Image.fusion) and [`Carbon.Image:Component.Presentation.Picture`](Resources/Private/Fusion/Component/Presentation/Picture.fusion)

[](#carbonimagecomponentpresentationimage-and-carbonimagecomponentpresentationpicture)

Outputs an image.

PropertyImagePictureDescriptionTypeDefault valueRead setting`imageSource`✓✓\[ImageSource FusionObject\]`null``thumbnailPreset`✓✓Set width and/or height via named thumbnail preset from setting `Neos.Media.thumbnailPresets``string``null``variantPreset`✓✓Select image variant via named variant preset, given as `IDENTIFIER::VARIANTNAME` keys from setting `Neos.Media.variantPresets``string` or `array``null``width`✓✓Set the intended width`integer``null``height`✓✓Set the intended height`integer``null``srcset`✓✓Media descriptors like `'1.5x'` or `'600w'` of the default image`string` or `array``null``sizes`✓✓Sizes attribute`string` or `array``null``additionalFormats`✓`array` of `strings``[]``sources`✓Array of source definitions that supports the following keys: `imageSource`, `srcset`, `sizes`, `media`, `type``array``null``lazy`✓✓Enable lazyloading in usage with [lazysizes](https://github.com/aFarkas/lazysizes). This is disabled in backend`boolean``false``Carbon.Image.lazy.enabled``lazyClass`✓✓The CSS class to attach to the img-tags`string``'lazyload'``Carbon.Image.lazy.class``lazyWidth`✓✓The width of the thumbnail-src that is loaded first`integer``null``Carbon.Image.lazy.lazyWidth``loading`✓✓Set the `loading` attribute. Can be `'auto'`, `'lazy'` or `'eager'``string``null``objectFit`✓✓Can be `'cover'` or `'contain'``string``null``alternativeText`✓✓Set the `alt` attribute`string``null``title`✓✓Set the `title` attribute`string``null``class`✓✓Set the `class` attribute`string` or `array``null``id`✓✓Set the `id` attribute`string``null``style`✓✓Set the `style` attribute`string``null``figureTagName`✓✓Set tag name of the wrapping tag. If it set to `null`, the wrapping tag will not be written.`string``'figure'``figureAttributes`✓✓Set the attributes for the `figureTagName``Neos.Fusion:DataStructure``Neos.Fusion:DataStructure``content`✓✓If set and `figureTagName` is `'figure'`, a `figcaption` is rendered`string``null``linkAttributes`✓✓If set, the `` is wrapped with an link with this attributes`Neos.Fusion:DataStructure``null`### Integrational components

[](#integrational-components)

#### [`Carbon.Image:Component.Image`](Resources/Private/Fusion/Component/Integration/Image.fusion) and [`Carbon.Image:Component.Picture`](Resources/Private/Fusion/Component/Integration/Picture.fusion)

[](#carbonimagecomponentimage-and-carbonimagecomponentpicture)

You can pass any value from `Carbon.Image:Component.Presentation.Image` / `Carbon.Image:Component.Presentation.Picture`. To keep it a bit shorter those are not listed.

PropertyDescriptionTypeDefault value`outputDummy``boolean``node.context.inBackend``image``string` or `'Neos\Media\Domain\Model\ImageInterface'``null``imageSourceSettings`You can pass all properties from [`Carbon.Image:Helper.ImageSource`](Resources/Private/Fusion/Helper/ImageSource.fusion)`array``null``link`Pass a node or a string. The link gets processed with `ConvertUris`. It will have no effect if `linkAttributes` is set.`string` or `'Neos\ContentRepository\Domain\Model\Node'``null``linkOptions``array``Carbon.Image:Helper.Link.Options``linkAdditonalAttributes`Pass any additional attributes to the link. You can even override `href`.`array``Neos.Fusion:DataStructure``lightbox`If set, the link for the lightbox gets generated. It will have no effect if `link` or `linkAttributes` is set.`boolean``Neos.Fusion:DataStructure``lightboxConfiguration`The configuration array for the lightbox`array`[Lightbox settings](Configuration/Settings.Carbon.yaml#L31-L43)`lightboxImage`Override the lightbox image`string` or `'Neos\Media\Domain\Model\ImageInterface'``this.image``linkAttributes`If set, it will override `lightbox` and `link``Neos.Fusion:DataStructure``null`### Helper

[](#helper)

#### [`Carbon.Image:Helper.Link.Attributes`](Resources/Private/Fusion/Helper/Link/Attributes.fusion)

[](#carbonimagehelperlinkattributes)

> This prototype is used by the integrational components [`Carbon.Image:Component.Image`](Resources/Private/Fusion/Component/Integration/Image.fusion) and [`Carbon.Image:Component.Picture`](Resources/Private/Fusion/Component/Integration/Picture.fusion).

It takes properties like `link`, `lightbox` and their options and return the attributes. If nothing is set it will return `false`.

#### [`Carbon.Image:Helper.Link.Options`](Resources/Private/Fusion/Helper/Link/Options.fusion)

[](#carbonimagehelperlinkoptions)

> This prototype is used by the integrational components [`Carbon.Image:Component.Image`](Resources/Private/Fusion/Component/Integration/Image.fusion) and [`Carbon.Image:Component.Picture`](Resources/Private/Fusion/Component/Integration/Picture.fusion).

You can set options related to `Neos.Neos:ConvertUris` and `Neos.Neos:NodeUri`.

#### [`Carbon.Image:Helper.AlternativeText`](Resources/Private/Fusion/Helper/AlternativeText.fusion)

[](#carbonimagehelperalternativetext)

> This prototype is used by the integrational components [`Carbon.Image:Component.Image`](Resources/Private/Fusion/Component/Integration/Image.fusion) and [`Carbon.Image:Component.Picture`](Resources/Private/Fusion/Component/Integration/Picture.fusion).

The idea behind this prototype is to return an alternative text based on the media fields.

 How to implementIf `alternativeText` is passed (e.g. from an property) this value is returned. Otherwise, if `property` (`title`, `caption` or `copyrightNotice`) is set, it read the field of the asset. Per default, the property is set to `caption` (based on the setting `Carbon.Image.alternativeText.property`), but you can it override with your own `Settings.yaml` or via Fusion:

```
prototype(Carbon.Image:Helper.AlternativeText) {
    property = 'title'
}
```

But this is kind of critcal if you multiple languages on a website. This is where the option `languageMapping` comes in. With this you can split (based on the setting `Carbon.Image.alternativeText.splitCharacter`, defaults to `||`) a string into the needed language. The easiest way to enable this, is to set the configuration `Carbon.Image.alternativeText.languageMapping`in your `Settings.yaml` like this:

```
Carbon:
    Image:
        alternativeText:
            languageMapping:
                en: 0
                de: 1
                fr: 2
```

but of course you can set this also via Fusion:

```
prototype(Carbon.Image:Helper.AlternativeText) {
    languageMapping = Neos.Fusion:DataStructure {
        en = 0
        de = 1
        fr = 2
    }
}
```

With this kind of setting, you can write the alternative text in the media field like this: `A cat || Eine Katze || Un chat`

To override the label in the media field you can a file called `MediaBrowser.xlf` in your translation folder:

```

                Caption ( English || German || French)
                Beschriftung (Englisch || Deutsch || Französisch)

```

You can override the current language by set the property `language`. Otherwise the current dimension `language` is used.

The string is always trimmed and all tags are stripped out. It no alternative text can be extraced, the Fusion will return `false`.

#### [`Carbon.Image:Helper.ImageSource`](Resources/Private/Fusion/Helper/ImageSource.fusion)

[](#carbonimagehelperimagesource)

With this helper you can pass any value (with the propery `image`) and you will get the corresponding image source from Kaleidoscope.

If `forceDummy` is set (defaults to `Configuration.Setting('Carbon.Image.dummy.force')`), you will get a `Sitegeist.Kaleidoscope:DummyImageSource`. If `image` is an instance of an `Neos\Media\Domain\Model\ImageInterface` you will get a `Sitegeist.Kaleidoscope:AssetImageSource`. If `image` is a string and starts with `resource` or `package`, you will get a `Sitegeist.Kaleidoscope:ResourceImageSource`. If `image` is a string and starts with `http`, you will get a `Sitegeist.Kaleidoscope:UriImageSource`. Otherwise, if `outputDummy` is set (defaults to `node.context.inBackend`), you will get `Sitegeist.Kaleidoscope:DummyImageSource`.

#### [`Carbon.Image:Helper.MinMaxImageSize`](Resources/Private/Fusion/Helper/MinMaxImageSize.fusion)

[](#carbonimagehelperminmaximagesize)

> This prototype is used by the presentational components [`Carbon.Image:Component.Presentation.Image`](Resources/Private/Fusion/Component/Presentation/Image.fusion)and [`Carbon.Image:Component.Presentation.Picture`](Resources/Private/Fusion/Component/Presentation/Picture.fusion).

This prototype takes a value and returns a string for the `srcset` (e.g. `150w, 300w, 450w, 600w`)

PropertyDescriptionTypeDefault value`size`The basis size (width or height)`integer``${value}``min`The minimal width of an image`integer``300``max`The maximal width of an image`integer``3900``step`If you set this to null, the steps generation gets deactivated, otherwise every step an image get generated`integer``150``multiplicator`Besides the steps, also these sizes get generated (`size` × `item` in `multiplicator`)`array of integers``${[2, 1.5, 1, 0.75, 0.5, 0.25]}`The lightbox
------------

[](#the-lightbox)

The markup is optimized to use this together with [Jonnitto.PhotoSwipe](https://github.com/jonnitto/Jonnitto.PhotoSwipe), but you can use any lightbox you want.

###  Health Score

48

—

FairBetter than 95% of packages

Maintenance54

Moderate activity, may be stable

Popularity31

Limited adoption so far

Community14

Small or concentrated contributor base

Maturity76

Established project with proven stability

 Bus Factor1

Top contributor holds 100% 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 ~60 days

Recently: every ~87 days

Total

49

Last Release

315d ago

Major Versions

1.3.2 → 2.0.22019-01-15

1.3.3 → 2.1.02019-05-16

v2.x-dev → 3.0.02021-10-30

v3.x-dev → 4.0.02023-12-24

### Community

Maintainers

![](https://www.gravatar.com/avatar/5fec51ac160a110a31a72a54ac29e276a447d8306205a052d35491ac9cf0589b?d=identicon)[jonnitto](/maintainers/jonnitto)

---

Top Contributors

[![jonnitto](https://avatars.githubusercontent.com/u/4510166?v=4)](https://github.com/jonnitto "jonnitto (166 commits)")

---

Tags

carbonfusionhacktoberfestimageneoscmshelperimagecarbonflowNeosFUSION

### Embed Badge

![Health badge](/badges/carbon-image/health.svg)

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

###  Alternatives

[carbon/includeassets

Include your assets (css, js) in an easy way into Neos

14228.6k10](/packages/carbon-includeassets)

PHPackages © 2026

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