--- title: "imgResource" manual: "TypoScript Explained" version: "main" permalink: "https://docs.typo3.org/permalink/t3tsref:imgresource@main" source: "Functions/Imgresource.rst" rendered: "2026-09-19T06:55:14+00:00" --- # imgResource {#imgresource} An imgResource one of the following: 1. A [resource](https://docs.typo3.org/permalink/t3tsref:confval-data-type-resource@main) plus imgResource properties. Filetypes can be anything among the allowed types defined in the configuration variable `$GLOBALS['TYPO3_CONF_VARS']['GFX']['imagefile_ext']`. Standard is gif,jpg,jpeg,tif,tiff,bmp,pcx,tga,png,pdf,ai,svg,webp. 1. A GIFBUILDER object. See the object reference for [GIFBUILDER](https://docs.typo3.org/permalink/t3tsref:gifbuilder@main). **Examples** Here "file" is an imgResource: **EXT:site_package/Configuration/Sets/Main/setup.typoscript** ```typoscript 10 = IMAGE 10 { file = fileadmin/toplogo.gif file.width = 200 } ``` GIFBUILDER: **EXT:site_package/Configuration/Sets/Main/setup.typoscript** ```typoscript 10 = IMAGE 10.file = GIFBUILDER 10.file { # GIFBUILDER properties here... } ``` - [Properties](https://docs.typo3.org/permalink/t3tsref:properties@main) - [Examples](https://docs.typo3.org/permalink/t3tsref:examples@main) ## Properties {#imgresource-properties} ### ext {#imgresource-ext} - **ext** - *Type:* string / [stdWrap](https://docs.typo3.org/permalink/t3tsref:stdwrap@main) - *Default:* web Target file extension for the processed image. The value `web` checks if the file extension is one of gif, jpg, jpeg, png, or svg and if not it will find the best target extension. The target extension must be in the list of file extensions perceived as images. This is defined in `$GLOBALS['TYPO3_CONF_VARS']['GFX']['imagefile_ext']` in the install tool. Standard is gif,jpg,jpeg,tif,tiff,bmp,pcx,tga,png,pdf,ai,svg,webp. ### width {#imgresource-width} - **width** - *Type:* integer / [stdWrap](https://docs.typo3.org/permalink/t3tsref:stdwrap@main) If both the width and the height are set and one of the numbers is appended by an `m`, the proportions will be preserved and thus width and height are treated as maximum dimensions for the image. The image will be scaled to fit into the rectangle of the dimensions width and height. If both the width and the height are set and at least one of the numbers is appended by a `c`, crop-scaling will be enabled. This means that the proportions will be preserved and the image will be scaled to fit **around** a rectangle with width/height dimensions. Then, a centered portion from **inside** of the image (size defined by width/height) will be cut out. The `c` can have a percentage value (-100 ... +100) after it, which defines how much the cropping will be moved off the center to the border. Notice that you can only use either `m` *or* `c` at the same time! **Examples** This crops 120x80px from the center of the scaled image: **EXT:site_package/Configuration/Sets/Main/setup.typoscript** ```typoscript lib.image { width = 120c height = 80c } ``` This crops 100x100px; from landscape-images at the left and portrait- images centered: **EXT:site_package/Configuration/Sets/Main/setup.typoscript** ```typoscript lib.image { width = 100c-100 height = 100c } ``` This crops 100x100px; from landscape-images a bit right of the center and portrait-images a bit higher than centered: **EXT:site_package/Configuration/Sets/Main/setup.typoscript** ```typoscript lib.image { width = 100c+30 height = 100c-25 } ``` ### height {#imgresource-height} - **height** - *Type:* integer / [stdWrap](https://docs.typo3.org/permalink/t3tsref:stdwrap@main) See [width](https://docs.typo3.org/permalink/t3tsref:imgresource-width@main). ### params {#imgresource-params} - **params** - *Type:* [string](https://docs.typo3.org/permalink/t3tsref:data-type-string@main) / [stdWrap](https://docs.typo3.org/permalink/t3tsref:stdwrap@main) GraphicsMagick/ImageMagick command line: fx. `-rotate 90`, `-negate` or `-quality 90` ### sample {#imgresource-sample} - **sample** - *Type:* [boolean](https://docs.typo3.org/permalink/t3tsref:data-type-boolean@main) - *Default:* 0 If set, `-sample` is used to scale images instead of `-geometry`. Sample does not use anti-aliasing and is therefore much faster. ### noScale {#imgresource-noscale} - **noScale** - *Type:* [boolean](https://docs.typo3.org/permalink/t3tsref:data-type-boolean@main) / [stdWrap](https://docs.typo3.org/permalink/t3tsref:stdwrap@main) - *Default:* 0 If set, the image itself will never be scaled. Only width and height are calculated according to the other properties, so that the image is *displayed* resized, but the original file is used. Can be used for creating PDFs or printing of pages, where the original file could provide much better quality than a rescaled one. **Examples** Here `test.jpg` could have 1600 x 1200 pixels for example: **EXT:site_package/Configuration/Sets/Main/setup.typoscript** ```typoscript file = fileadmin/test.jpg file.width = 240m file.height = 240m file.noScale = 1 ``` This example results in an image tag like the following. Note that `src="fileadmin/test.jpg"` is the *original* file: ```html ``` ### crop {#imgresource-crop} - **crop** - *Type:* [string](https://docs.typo3.org/permalink/t3tsref:data-type-string@main) / [stdWrap](https://docs.typo3.org/permalink/t3tsref:stdwrap@main) - *Default:* not-set (when file/image is a file_reference the crop value of It is possible to define an area that should be taken (cropped) from the image. When not defined in typoscript the value will be taken from the file_reference when possible. With this setting you can override this behavior. SVG images are processed natively in SVG during cropping. the file reference is used) **Examples** Disable cropping set by the editor in the back-end: **EXT:site_package/Configuration/Sets/Main/setup.typoscript** ```typoscript tt_content.image.20.1.file.crop = ``` Overrule/set cropping for all images: **EXT:site_package/Configuration/Sets/Main/setup.typoscript** ```typoscript tt_content.image.20.1.file.crop = 50,50,100,100 ``` Natively crop a SVG image: **EXT:site_package/Configuration/Sets/Main/setup.typoscript** ```typoscript page.10 = IMAGE page.10.file = 2:/myfile.svg page.10.file.crop = 20,20,500,500 ``` ### cropVariant {#imgresource-cropvariant} - **cropVariant** - *Type:* [string](https://docs.typo3.org/permalink/t3tsref:data-type-string@main) - *Default:* default Since it's possible to define certain [crop variants](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ApiOverview/CropVariants/Index.html#cropvariants) you can specify which one to use here. **Examples** Use 'desktop' crop variant: **EXT:site_package/Configuration/Sets/Main/setup.typoscript** ```typoscript tt_content.image.20.1.file { crop.data = file:current:crop cropVariant = desktop } ``` ### frame {#imgresource-frame} - **frame** - *Type:* [integer](https://docs.typo3.org/permalink/t3tsref:data-type-integer@main) / [stdWrap](https://docs.typo3.org/permalink/t3tsref:stdwrap@main) Chooses the frame in a PDF or GIF file. "" = first frame (zero) ### import {#imgresource-import} - **import** - *Type:* [path](https://docs.typo3.org/permalink/t3tsref:data-type-path@main) / [stdWrap](https://docs.typo3.org/permalink/t3tsref:stdwrap@main) *value* should be set to the path of the file with [stdWrap](https://docs.typo3.org/permalink/t3tsref:stdwrap@main) you get the filename from the data-array **Examples** This returns the first image in the field "image" from the data-array: **EXT:site_package/Configuration/Sets/Main/setup.typoscript** ```typoscript tt_content.image.20.1.file { import = uploads/pics/ import.field = image import.listNum = 0 } ``` ### treatIdAsReference {#imgresource-treatidasreference} - **treatIdAsReference** - *Type:* [boolean](https://docs.typo3.org/permalink/t3tsref:data-type-boolean@main) / [stdWrap](https://docs.typo3.org/permalink/t3tsref:stdwrap@main) - *Default:* 0 If set, given UIDs are interpreted as UIDs to sys_file_reference instead of to sys_file. This allows using file references, for example with `import.data = levelmedia: ...`. ### maxW {#imgresource-maxw} - **maxW** - *Type:* integer / [stdWrap](https://docs.typo3.org/permalink/t3tsref:stdwrap@main) Maximum width ### maxH {#imgresource-maxh} - **maxH** - *Type:* integer / [stdWrap](https://docs.typo3.org/permalink/t3tsref:stdwrap@main) Maximum height ### minW {#imgresource-minw} - **minW** - *Type:* integer / [stdWrap](https://docs.typo3.org/permalink/t3tsref:stdwrap@main) Minimum width (overrules maxW/maxH) ### minH {#imgresource-minh} - **minH** - *Type:* integer / [stdWrap](https://docs.typo3.org/permalink/t3tsref:stdwrap@main) Minimum height (overrules maxW/maxH) ### stripProfile {#imgresource-stripprofile} - **stripProfile** - *Type:* [boolean](https://docs.typo3.org/permalink/t3tsref:data-type-boolean@main) - *Default:* 0 If set, the GraphicsMagick/ImageMagick-command will use a stripProfile-command which shrinks the generated thumbnails. See the Install Tool for options and details. If `processor_stripColorProfileByDefault` is set in the Install Tool, you can deactivate it by setting `stripProfile=0`. **Examples** **EXT:site_package/Configuration/Sets/Main/setup.typoscript** ```typoscript 10 = IMAGE 10.file = fileadmin/images/image1.jpg 10.file.stripProfile = 1 ``` ### Masking (m) {#imgresource-masking} - **Masking:** (Black hides, white shows) #### m.mask {#imgresource-masking-mask} - **m.mask** - *Type:* [imgResource](https://docs.typo3.org/permalink/t3tsref:data-type-imgresource@main) The mask with which the image is masked onto `m.bgImg`. Both `m.mask` and `m.bgImg` **is scaled to fit** the size of the imgResource image! **Note:** Both `m.mask` and `m.bgImg` must be valid images. #### m.bgImg {#imgresource-masking-bgimg} - **m.bgImg** - *Type:* [imgResource](https://docs.typo3.org/permalink/t3tsref:data-type-imgresource@main) **Note:** Both `m.mask` and `m.bgImg` must be valid images. #### m.bottomImg {#imgresource-masking-bottomimg} - **m.bottomImg** - *Type:* [imgResource](https://docs.typo3.org/permalink/t3tsref:data-type-imgresource@main) An image masked by `m.bottomImg_mask` onto `m.bgImg` before the imgResources is masked by `m.mask`. Both `m.bottomImg` and `m.bottomImg_mask` **is scaled to fit** the size of the imgResource image! This is most often used to create an underlay for the imgResource. **Note:** Both "m.bottomImg" and `m.bottomImg_mask` must be valid images. #### m.bottomImg_mask {#imgresource-masking-bottomimg-mask} - **m.bottomImg_mask** - *Type:* [imgResource](https://docs.typo3.org/permalink/t3tsref:data-type-imgresource@main) (optional) **Note:** Both `m.bottomImg` and `m.bottomImg_mask` must be valid images. ## Examples {#imgresource-examples} This scales the image `fileadmin/toplogo.png` to the width of 200 pixels: **EXT:site_package/Configuration/Sets/Main/setup.typoscript** ```typoscript file = fileadmin/toplogo.png file.width = 200 ```