--- title: "Image rendering" manual: "Headless" version: "main" permalink: "https://docs.typo3.org/permalink/friendsoftypo3/headless:images@main" source: "Developer/Images.rst" rendered: "2026-10-14T09:29:03+00:00" --- # Image rendering {#images} ## FileUtility {#fileutility} The file rendering in `EXT:headless` is handled by `FileUtility` which renders the following JSON for each file: ```json "publicUrl": "https://www.example.org/fileadmin/_processed_/6/c/csm_my-image_51125112.jpg" "properties": { "mimeType": "image/jpeg", "type": "image", "filename": "csm_my-image_51125112.jpg", "link": null, "linkData": null, "originalUrl": "https://www.example.org/fileadmin/my-image.jpg", "uidLocal": "123", "fileReferenceUid": "234", "size": "50 KB", "title": null, "alternative": null, "description": null, "dimensions": { "width": "300", "height": "100", }, "cropDimensions": { "width": "300", "height": "100", }, "crop": { ... }, "autoplay": null, "extension": null } ``` The file rendering can be simplified via `legacyReturn` = 0 processing configuration flag ```typoscript lib.meta { fields { ogImage = TEXT ogImage { dataProcessing { 10 = FriendsOfTYPO3\Headless\DataProcessing\FilesProcessor 10 { as = media references.fieldName = og_image processingConfiguration { legacyReturn = 0 } } } } } } ``` Will output: ```json "url": "https://www.example.org/fileadmin/_processed_/6/c/csm_my-image_51125112.jpg" "mimeType": "image/jpeg", "type": "image", "filename": "csm_my-image_51125112.jpg", "originalUrl": "https://www.example.org/fileadmin/my-image.jpg", "link": null, "uidLocal": "123", "fileReferenceUid": "234", "size": "50 KB", "title": null, "alternative": null, "description": null, "dimensions": { "width": "300", "height": "100", }, "cropDimensions": { "width": "300", "height": "100", }, "cropVariants": { "default": "..." }, "autoplay": null, "extension": null ``` `cropVariants` only appears for images whose crop configuration defines more than one crop variant. ### EnrichFileDataEvent {#enrichfiledataevent} `FileUtility` is emitting the event `EnrichFileDataEvent` for manipulating the `properties` array. To add a listener add this to your `Configuration/Services.yaml`: ```yaml My\Extension\EventListener\TweakFileData: tags: - name: event.listener identifier: 'tweak-file-data' event: FriendsOfTYPO3\Headless\Event\EnrichFileDataEvent ``` ## FilesProcessor {#filesprocessor} `headless` provides its own `FilesProcessor` to render files. Here's an example of how the `og_image` of a page is being rendered via TypoScript: ```typoscript lib.meta { fields { ogImage = TEXT ogImage { dataProcessing { 10 = FriendsOfTYPO3\Headless\DataProcessing\FilesProcessor 10 { as = media references.fieldName = og_image processingConfiguration { returnFlattenObject = 1 } } } } } } ``` ### Configuration {#configuration} The rendering configuration can be set via the property `processingConfiguration` and provides the following sub-properties: - `legacyReturn` (0|1): Allows to control new simplified output or old system (old system by default) - `linkResult` (0|1): Allows to define if file object should return only url of defined link or whole LinkResult object - `cacheBusting` (0|1): Allows to enable cacheBusting urls for processed files (enabled globally by the `headless.assetsCacheBusting` feature flag) - `width`, `height`, `minWidth`, `minHeight`, `maxWidth`, `maxHeight`: image processing instructions passed to the core processor - `cropVariant` (name): render a specific crop variant (default `default`) - `processGif` (0|1): enable optional processing of gif files (default off) - `outputCropArea` (0|1): include the resolved crop area in the output - `conditionalCropVariant` (0|1): Allows conditionally autogenerate files with defined variants if set (if not all variants are returned) - `processPdfAsImage` (0|1): Enabled optional processing pdf files as image (default off) - `processSvg` (0|1): Enabled optional processing svg files (default off) - `properties.byType` (0|1): Allows filter file properties by type (i.e. do not return video properties on images) - `properties.defaultFieldsByType` (coma separated list of fields): Default fields for when enabled option `properties.byType` - `properties.defaultImageFields` (coma separated list of fields): Default fields for image type when enabled option `properties.byType` - `properties.defaultVideoFields` (coma separated list of fields): Default fields for video type when enabled option `properties.byType` - `properties.includeOnly` (string, comma separated): Configure what file properties to return - `properties.flatten` (0|1): Flatten nested properties (dimensions array) to use with `properties.includeOnly` - `returnFlattenObject`: without that flag an array of (multiple) images is rendered. Set this if you're only rendering 1 image and want to reduce nesting. - `delayProcessing`: can be used to skip processing of images (and have them simply collected with the `FilesProcessor`), in order to have them processed by the next processor in line (which is generally `GalleryProcessor`). - `fileExtension`: can be used to convert the images to any desired format, e.g. `webp`. - `autogenerate`: *\`retina2x\`: set this to render an additional image URI in high quality (200%).* `lqip`: set this to render an additional image URI with low quality (10%). \* also custom defined size & file formats see example below ```typoscript 10 = FriendsOfTYPO3\Headless\DataProcessing\FilesProcessor 10 { ... processingConfiguration { delayProcessing = 1 } } 20 = FriendsOfTYPO3\Headless\DataProcessing\GalleryProcessor 20 { ... autogenerate { retina2x = 1 customFileWebp { fileExtension = webp factor = 1.0 } customTinyJpg { fileExtension = jpg factor = 0.2 } } } ``` ```typoscript 10 = FriendsOfTYPO3\Headless\DataProcessing\FilesProcessor 10 { ... processingConfiguration { # (1 by default = legacy output; set 0 for the new simplified format) legacyReturn = 0 # Return whole LinkResult object instead simple url linkResult = 1 # check if we need to conditionally check if we should generate crop variants conditionalCropVariant = 1 # Generate cacheBusting urls for images and video files cacheBusting = 1 properties { # return props by mimeType byType = 1 # return only properties defined below includeOnly = alternative,width,height # you can also alias fields # includeOnly = alternative as alt,width,height # with includeOnly you can use option `flatten` to flatten dimensions array flatten = 1 } } } ``` ## GalleryProcessor {#images-galleryprocessor} ### Configuration {#configuration-1} The rendering configuration is set directly on the processor: **all** options of the `processingConfiguration` block documented above (`legacyReturn`, `fileExtension`, `cropVariant`, …) are read from the processor's top-level configuration — there is no `processingConfiguration.` sub-key. Default `as` is `gallery`. The processor also supports `appendData` (`1` keeps the raw record data; absent or `0` — the default — strips `data` from the result) and `cropVariant` to select the crop variant used for the width/height calculation (default `default`). - `maxGalleryWidth`: set to the core constant `{$styles.content.textmedia.maxW}` - `maxGalleryWidthInText`: set to the core constant `{$styles.content.textmedia.maxWInText}` - `columnSpacing`: set to the core constant `{$styles.content.textmedia.columnSpacing}` - `borderWidth`: set to the core constant `{$styles.content.textmedia.borderWidth}` - `borderPadding`: set to the core constant `{$styles.content.textmedia.borderPadding}` - `autogenerate` *\`retina2x\`* `lqip` \* custom keys with `factor` / `fileExtension` — same syntax as in the FilesProcessor example above