---
title: "IMAGE"
manual: "TypoScript Explained"
version: "13.4"
permalink: "https://docs.typo3.org/permalink/t3tsref:cobj-image@13.4"
source: "ContentObjects/Image/Index.rst"
rendered: "2026-09-19T07:15:48+00:00"
---

# IMAGE {#cobj-image}

Objects of type IMAGE return an image tag with the image file defined in the property
"file" and is processed using the properties that are set on the object.

**Note:** Gifbuilder also has an [IMAGE object](https://docs.typo3.org/permalink/t3tsref:gifbuilder-image@13.4) \-
it is not the same as the cObject described here; both are completely
different objects.

If you only need the file path to the image; regardless of whether it's been resized, the cObject
[IMG_RESOURCE](https://docs.typo3.org/permalink/t3tsref:cobj-img-resource@13.4) will return the file path.

-   [Properties](https://docs.typo3.org/permalink/t3tsref:properties@13.4)
-   [Examples](https://docs.typo3.org/permalink/t3tsref:examples@13.4)

## Properties {#cobj-image-properties}

### cache {#cobj-image-cache}

-   **cache**

    -   *Type:* [cache](https://docs.typo3.org/permalink/t3tsref:cache@13.4)

    See [cache function description](https://docs.typo3.org/permalink/t3tsref:cache@13.4) for details.

### if {#cobj-image-if}

-   **if**

    -   *Type:* [->if](https://docs.typo3.org/permalink/t3tsref:if@13.4)

    If "if" returns false, the image is not shown!

### file {#cobj-image-file}

-   **file**

    -   *Type:* [->imgResource](https://docs.typo3.org/permalink/t3tsref:imgresource@13.4)

### params {#cobj-image-params}

-   **params**

    -   *Type:* [string](https://docs.typo3.org/permalink/t3tsref:data-type-string@13.4) / [stdWrap](https://docs.typo3.org/permalink/t3tsref:stdwrap@13.4)

    HTML \<IMG> parameters

### altText {#cobj-image-alttext}

-   **altText**

    -   *Type:* [string](https://docs.typo3.org/permalink/t3tsref:data-type-string@13.4) / [stdWrap](https://docs.typo3.org/permalink/t3tsref:stdwrap@13.4)

    If no alt text is specified, an empty alt text will be used.

### titleText {#cobj-image-titletext}

-   **titleText**

    -   *Type:* [string](https://docs.typo3.org/permalink/t3tsref:data-type-string@13.4) / [stdWrap](https://docs.typo3.org/permalink/t3tsref:stdwrap@13.4)

### emptyTitleHandling {#cobj-image-emptytitlehandling}

-   **emptyTitleHandling**

    -   *Type:* [string](https://docs.typo3.org/permalink/t3tsref:data-type-string@13.4) / [stdWrap](https://docs.typo3.org/permalink/t3tsref:stdwrap@13.4)
    -   *Default:* useAlt

    Value can be "keepEmpty" to preserve an empty title attribute, or
    "useAlt" to use the alt attribute instead.

### layoutKey {#cobj-image-layoutkey}

-   **layoutKey**

    -   *Type:* [string](https://docs.typo3.org/permalink/t3tsref:data-type-string@13.4) / [stdWrap](https://docs.typo3.org/permalink/t3tsref:stdwrap@13.4)
    -   *Default:* default

    Defines the render layout for the IMAGE. The render layout is the HTML Code for the IMAGE itself.
    Default values include `default`, `srcset`, `picture`, `data`.
    Each option represents a different solution to render the HTML Code of the IMAGE. The default code
    renders the img-tag as a plain html tag with the different attributes.

    When implementing a responsive layout you need different image sizes for the different displays and resolutions of your layout. Depending on
    the HTML framework, the capabilities of desired browsers and the used javascript library for progressive enhancement you can choose either one of the predefined layouts
    or you can define a new layout of your own by adding an additional layout key.

    If you don't have a responsive HTML layout you should use the default layout.

    -   `default` renders a normal non-responsive image as a `<img>` tag:

        ```text
        <img src="###SRC###"
             width="###WIDTH###"
             height="###HEIGHT###" ###PARAMS### ###ALTPARAMS### ###SELFCLOSINGTAGSLASH###>
        ```
    -   `srcset` renders an image tag pointing to a set of images for the different resolutions.
        They are referenced inside the `srcset` attribute the `<img>` tag for each defined resolution.
        Each image is actually rendered by TYPO3. Srcset is a proposed addition to HTML5 ([https://www.w3.org/TR/html-srcset/](https://www.w3.org/TR/html-srcset/)).

        ```text
        <img src="###SRC###"
             srcset="|*|###SRC### ###SRCSETCANDIDATE###,|*|###SRC### ###SRCSETCANDIDATE###" ###PARAMS### ###ALTPARAMS######SELFCLOSINGTAGSLASH###>
        ```
    -   `picture` renders a picture tag containing source tags for each resolution
        and an `<img>` tag for the default image.

        ```text
        <picture>
           <source srcset="###SRC###"
                   media="###MEDIAQUERY###"###SELFCLOSINGTAGSLASH###>
           <img src="###SRC###" ###PARAMS### ###ALTPARAMS######SELFCLOSINGTAGSLASH###>
        </picture>
        ```
    -   `data` renders an image tag containing data-keys for the different resolutions:

        ```text
        <img src="###SRC###"
             data-###DATAKEY###="###SRC###" ###PARAMS### ###ALTPARAMS######SELFCLOSINGTAGSLASH###>
        ```

### layout {#cobj-image-layout}

-   **layout**

    -   *Type:* array

    HTML code definition for the different [layoutKey](https://docs.typo3.org/permalink/t3tsref:cobj-image-layoutkey@13.4).

### layout.layoutKey {#cobj-image-layout-layoutkey}

-   **layout.layoutKey**

    -   *Type:* array

    Definition for the HTML rendering for the named
    [layoutKey](https://docs.typo3.org/permalink/t3tsref:cobj-image-layoutkey@13.4). Depending on your needs you can use the
    existing pre-defined layoutKey or you can define your own element for
    your responsive layout.

    **Example:**

    **EXT:site_package/Configuration/TypoScript/setup.typoscript**

    ```typoscript
    picture {
      element = <picture>###SOURCECOLLECTION###<img src="###SRC###" ###PARAMS### ###ALTPARAMS### ###SELFCLOSINGTAGSLASH###></picture>
      source = <source srcset="###SRC###" media="###MEDIAQUERY###" ###SELFCLOSINGTAGSLASH###>
    }

    ```

### layout.layoutKey.element {#cobj-image-layout-layoutkey-element}

-   **layout.layoutKey.element**

    -   *Type:* [string](https://docs.typo3.org/permalink/t3tsref:data-type-string@13.4)

    The outer element definition for the HTML rendering of the image.
    Possible markers are mainly all parameters which can be defined in the
    IMAGE object, e.g.:

    -   `###SRC###` the file URL for the src attribute
    -   `###WIDTH###` the width of the image for the width tag (only the
        width value)
    -   `###HEIGHT###` the height of the image for the height tag (only the
        width value)
    -   `###PARAMS###` additional params defined in the IMAGE object (as
        complete attribute)
    -   `###ALTPARAMS###` additional alt params defined in the IMAGE object
        (as complete attribute)
    -   `###SELFCLOSINGTAGSLASH###` renders the closing slash of the tag,
        depending on the setting of [config.doctype](https://docs.typo3.org/permalink/t3tsref:setup-config-doctype@13.4)
    -   `###SOURCECOLLECTION###` the additional sources of the image
        depending on the different usage in responsive webdesign. The
        definition of the sources is declared inside
        [layout.layoutKey.source](https://docs.typo3.org/permalink/t3tsref:cobj-image-layout-layoutkey-source@13.4)

### layout.layoutKey.source {#cobj-image-layout-layoutkey-source}

-   **layout.layoutKey.source**

    -   *Type:* [stdWrap](https://docs.typo3.org/permalink/t3tsref:stdwrap@13.4)

    Defines the HTML code for the `###SOURCECOLLECTION###`
    of the [layout.layoutKey.element](https://docs.typo3.org/permalink/t3tsref:cobj-image-layout-layoutkey-element@13.4).
    Possible markers in the out of the box configuration are:

    -   `###SRC###` the file URL for the src attribute
    -   `###WIDTH###` the width of the image for the width tag (only the width value)
    -   `###HEIGHT###` the height of the image for the height tag (only the width value)
    -   `###SELFCLOSINGTAGSLASH###` renders the closing slash of the tag,
        depending on the setting of [config.doctype](https://docs.typo3.org/permalink/t3tsref:setup-config-doctype@13.4)
    -   `###SRCSETCANDIDATE###` is the value of the srcsetCandidate defined in each SourceCollection.DataKey
    -   `###MEDIAQUERY###` is the value of the mediaQuery defined in each SourceCollection.DataKey
    -   `###DATAKEY###` is the name of the dataKey defined in the [sourceCollection](https://docs.typo3.org/permalink/t3tsref:cobj-image-sourcecollection@13.4)

    You can define additional markers by adding more datakeys to the collection.
    ###SRCSETCANDIDATE###, ###MEDIAQUERY###, ###DATAKEY### are already defined
    as additional datakeys in the out of the box typoscript. Thus can be
    overwritten by your typoscript.

### sourceCollection {#cobj-image-sourcecollection}

-   **sourceCollection**

    -   *Type:* array

    For responsive images you need different image resolutions for each
    output device and output mode (portrait vs. landscape).
    `sourceCollection` defines the different resolutions for image
    rendering, normally you would define at least one
    `sourceCollection` per layout breakpoint. The amount of
    sourceCollections, the name and the specification for the
    sourceCollections will be defined by the HTML/CSS/JS code you are
    using. The configuration of the sourceCollection defines the size of
    the image which is rendered.

    Each resolution should be set up as separate array in the
    `sourceCollection`. Each `sourceCollection` consists of
    different [dataKey](https://docs.typo3.org/permalink/t3tsref:cobj-image-datakey@13.4) properties which you can
    define to suit your needs.

    **EXT:site_package/Configuration/TypoScript/setup.typoscript**

    ```typoscript
    sourceCollection {
      small {
        width = 200

        srcsetCandidate = 600w
        mediaQuery = (max-device-width: 600px)
        dataKey = small
      }
      smallRetina {
        if.directReturn = 1

        width = 200
        pixelDensity = 2

        srcsetCandidate = 600w 2x
        mediaQuery = (max-device-width: 600px) AND (min-resolution: 192dpi)
        dataKey = smallRetina
      }
    }

    ```

### sourceCollection.dataKey {#cobj-image-datakey}

-   **sourceCollection.dataKey**

    -   *Type:* [stdWrap](https://docs.typo3.org/permalink/t3tsref:stdwrap@13.4)

    Definition of your image size definition depending on your responsive
    layout, breakpoints and display density.

### sourceCollection.dataKey.if {#cobj-image-datakey-if}

-   **sourceCollection.dataKey.if**

    -   *Type:* [if](https://docs.typo3.org/permalink/t3tsref:if@13.4)

    Renders only if the condition is met, this is evaluated before any
    execution of code.

### sourceCollection.dataKey.pixelDensity {#cobj-image-datakey-pixeldensity}

-   **sourceCollection.dataKey.pixelDensity**

    -   *Type:* [integer](https://docs.typo3.org/permalink/t3tsref:data-type-integer@13.4) / [stdWrap](https://docs.typo3.org/permalink/t3tsref:stdwrap@13.4)
    -   *Default:* 1

    Defines the density of the rendered Image, e.g. a retina display would
    have a density of 2, the density is a multiplier for the image
    dimensions: If the pixelDensity is set to 2 and the width is set to
    200 the generated image file will have a width of 400 but will be
    treated inside the html code as 200 pixels.

### sourceCollection.dataKey.width {#cobj-image-datakey-width}

-   **sourceCollection.dataKey.width**

    -   *Type:* [stdWrap](https://docs.typo3.org/permalink/t3tsref:stdwrap@13.4)

    Defines the width for the html code of the image defined in this
    source collection. For the image file itself the width will be multiplied by
    [dataKey.pixelDensity](https://docs.typo3.org/permalink/t3tsref:cobj-image-datakey-pixeldensity@13.4).

### sourceCollection.dataKey.height {#cobj-image-datakey-height}

-   **sourceCollection.dataKey.height**

    -   *Type:* [stdWrap](https://docs.typo3.org/permalink/t3tsref:stdwrap@13.4)

    Defines the height for the html code of the image defined in this
    source collection. For the image file itself the height will be multiplied by
    [dataKey.pixelDensity](https://docs.typo3.org/permalink/t3tsref:cobj-image-datakey-pixeldensity@13.4).

### sourceCollection.dataKey.maxW {#cobj-image-datakey-maxw}

-   **sourceCollection.dataKey.maxW**

    -   *Type:* [stdWrap](https://docs.typo3.org/permalink/t3tsref:stdwrap@13.4)

    Defines the maxW for the html code of the image defined in this
    source collection. For the image file itself the maxW will be multiplied by
    [dataKey.pixelDensity](https://docs.typo3.org/permalink/t3tsref:cobj-image-datakey-pixeldensity@13.4).

### sourceCollection.dataKey.maxH {#cobj-image-datakey-maxh}

-   **sourceCollection.dataKey.maxH**

    -   *Type:* [stdWrap](https://docs.typo3.org/permalink/t3tsref:stdwrap@13.4)

    Defines the maxH for the html code of the image defined in this
    source collection. For the image file itself the maxH will be multiplied by
    [dataKey.pixelDensity](https://docs.typo3.org/permalink/t3tsref:cobj-image-datakey-pixeldensity@13.4).

### sourceCollection.dataKey.minW {#cobj-image-datakey-minw}

-   **sourceCollection.dataKey.minW**

    -   *Type:* [stdWrap](https://docs.typo3.org/permalink/t3tsref:stdwrap@13.4)

    Defines the minW for the html code of the image defined in this
    source collection. For the image file itself the minW will be multiplied by
    [dataKey.pixelDensity](https://docs.typo3.org/permalink/t3tsref:cobj-image-datakey-pixeldensity@13.4).

### sourceCollection.dataKey.minH {#cobj-image-datakey-minh}

-   **sourceCollection.dataKey.minH**

    -   *Type:* [stdWrap](https://docs.typo3.org/permalink/t3tsref:stdwrap@13.4)

    Defines the minH for the html code of the image defined in this
    source collection. For the image file itself the minH will be multiplied by
    [dataKey.pixelDensity](https://docs.typo3.org/permalink/t3tsref:cobj-image-datakey-pixeldensity@13.4).

### sourceCollection.dataKey.quality {#cobj-image-datakey-quality}

-   **sourceCollection.dataKey.quality**

    -   *Type:* [integer](https://docs.typo3.org/permalink/t3tsref:data-type-integer@13.4)

    Defines the quality of the rendered images on a scale from 1-100.

### sourceCollection.dataKey.\* {#cobj-image-datakey-others}

-   **sourceCollection.dataKey.\***

    -   *Type:* [string](https://docs.typo3.org/permalink/t3tsref:data-type-string@13.4)

    You can define additional key value pairs which won't be used for
    setting the image size, but will be available as additional markers for
    the image template. See the example mediaquery.

### linkWrap {#cobj-image-linkwrap}

-   **linkWrap**

    -   *Type:* [Wrap](https://docs.typo3.org/permalink/t3tsref:data-type-wrap@13.4) / [stdWrap](https://docs.typo3.org/permalink/t3tsref:stdwrap@13.4)

    (before ".wrap")

### imageLinkWrap {#cobj-image-imagelinkwrap}

-   **imageLinkWrap**

    -   *Type:* [boolean](https://docs.typo3.org/permalink/t3tsref:data-type-boolean@13.4) / [->imageLinkWrap](https://docs.typo3.org/permalink/t3tsref:imagelinkwrap@13.4)

    **Note:** Only active if linkWrap is **not** set and file is
    **not** [GIFBUILDER](https://docs.typo3.org/permalink/t3tsref:gifbuilder@13.4) (as it works with the original
    image file).

### wrap {#cobj-image-wrap}

-   **wrap**

    -   *Type:* [wrap](https://docs.typo3.org/permalink/t3tsref:data-type-wrap@13.4) / [stdWrap](https://docs.typo3.org/permalink/t3tsref:stdwrap@13.4)

    Wrap for the image tag.

### stdWrap {#cobj-image-stdwrap}

-   **stdWrap**

    -   *Type:* [->stdWrap](https://docs.typo3.org/permalink/t3tsref:stdwrap@13.4)

## Examples {#cobj-image-examples}

### Standard rendering {#cobj-image-examples-standard}

**EXT:site_package/Configuration/TypoScript/setup.typoscript**

```typoscript
page.10 = IMAGE
# toplogo.png has the dimensions 300 x 150 pixels.
page.10 {
  file = fileadmin/toplogo.png
  params = style="margin: 0px 20px;"
  wrap = |<br>
}

```

This returns:

**Example output**

```html
<img src="/fileadmin/toplogo.png"
     width="300"
     height="150"
     style="margin: 0px 20px;"
     alt=""><br>
```

### Responsive/adaptive rendering {#cobj-image-examples-responsive}

**EXT:site_package/Configuration/TypoScript/setup.typoscript**

```typoscript
30 = IMAGE
30 {
  file = fileadmin/imagefilenamename.jpg
  file.width = 100

  layoutKey = default
  layout {

    default {
      element = <img src="###SRC###" width="###WIDTH###" height="###HEIGHT###" ###PARAMS### ###ALTPARAMS### ###SELFCLOSINGTAGSLASH###>
      source =
    }

    srcset {
      element = <img src="###SRC###" srcset="###SOURCECOLLECTION###" ###PARAMS### ###ALTPARAMS### ###SELFCLOSINGTAGSLASH###>
      source = |*|###SRC### ###SRCSETCANDIDATE###,|*|###SRC### ###SRCSETCANDIDATE###
    }

    picture {
      element = <picture>###SOURCECOLLECTION###<img src="###SRC###" ###PARAMS### ###ALTPARAMS### ###SELFCLOSINGTAGSLASH###></picture>
      source = <source srcset="###SRC###" media="###MEDIAQUERY###" ###SELFCLOSINGTAGSLASH###>
    }

    data {
      element = <img src="###SRC###" ###SOURCECOLLECTION### ###PARAMS### ###ALTPARAMS### ###SELFCLOSINGTAGSLASH###>
      source.noTrimWrap = | data-###DATAKEY###="###SRC###"|
    }
  }

  sourceCollection {
    small {
      width = 200

      srcsetCandidate = 800w
      mediaQuery = (min-device-width: 800px)
      dataKey = small
    }
    smallHires {
      if.directReturn = 1
      width = 300
      pixelDensity = 2

      srcsetCandidate = 800w 2x
      mediaQuery = (min-device-width: 800px) AND (foobar)
      dataKey = smallHires
      pictureFoo = bar
    }
  }
}
40 < 30
40.layoutKey = data
50 < 30
50.layoutKey = picture
60 < 30
60.layoutKey = srcset

```

This returns as an example all per default possible HTML output:

**Example output**

```html
<img src="/fileadmin/_processed_/imagefilenamename_595cc36c48.png"
     width="600" height="423" alt="">
<img src="/fileadmin/_processed_/imagefilenamename_595cc36c48.png"
     data-small="/fileadmin/_processed_/imagefilenamename_595cc36c48.png"
     data-smallRetina="/fileadmin/_processed_/imagefilenamename_42fb68d642.png"
     alt="">
<picture>
  <source srcset="/fileadmin/_processed_/imagefilenamename_595cc36c48.png"
          media="(max-device-width: 600px)">
  <source srcset="/fileadmin/_processed_/imagefilenamename_42fb68d642.png"
          media="(max-device-width: 600px) AND (min-resolution: 192dpi)">
  <img src="/fileadmin/_processed_/imagefilenamename_595cc36c48.png"
       alt="">
</picture>
<img src="/fileadmin/_processed_/imagefilenamename_595cc36c48.png"
     srcset="/fileadmin/_processed_/imagefilenamename_595cc36c48.png 600w,
             /fileadmin/_processed_/imagefilenamename_42fb68d642.png 600w 2x"
     alt="">
```