---
title: "FILES"
manual: "TypoScript Explained"
version: "main"
permalink: "https://docs.typo3.org/permalink/t3tsref:cobj-files@main"
source: "ContentObjects/Files/Index.rst"
rendered: "2026-09-19T06:55:14+00:00"
---

# FILES {#cobj-files}

A content object of type FILES uses the [File Abstraction Layer](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ApiOverview/Fal/Index.html#fal)
(FAL) and is used to display information about files.

-   [Properties](https://docs.typo3.org/permalink/t3tsref:properties@main)
-   [Special key: "references"](https://docs.typo3.org/permalink/t3tsref:special-key-references@main)
-   [Examples](https://docs.typo3.org/permalink/t3tsref:examples@main)

## Properties {#cobj-files-properties}

### cache {#cobj-files-cache}

-   **cache**

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

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

### files {#cobj-files-files}

-   **files**

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

    Comma-separated list of sys_file UIDs, which are loaded
    into the FILES object.

    **Example:**

    ```typoscript
    page.10 = FILES
    page.10.files = 12,15,16
    ```

### references {#cobj-files-references}

-   **references**

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

    Provides a way to load files from a file field (of type
    IRRE with sys_file_reference as child table). You can either
    provide a UID or a comma-separated list of UIDs from the
    database table sys_file_reference or you have to specify a
    table, uid and field name in the according sub-properties of
    "references". See further documentation of these
    sub-properties in the table below.

    **Examples:**

    ```typoscript
    references = 27,28
    ```

    This will get the items from the database table
    sys_file_reference with the UIDs 27 and 28.

    **EXT:site_package/Configuration/Sets/Main/setup.typoscript**

    ```typoscript
    references {
      table = tt_content
      uid = 256
      fieldName = image
    }

    ```

    This will fetch all relations to the image field of the
    tt_content record "256".

    **EXT:site_package/Configuration/Sets/Main/setup.typoscript**

    ```typoscript
    references {
      table = pages
      uid.data = page:uid
      fieldName = media
    }

    ```

    This will fetch all items related to the page.media field.

### collections {#cobj-files-collections}

-   **collections**

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

    Comma-separated list of `sys_file_collection` UIDs, which
    are loaded into the `FILES` object.

### folders {#cobj-files-folders}

-   **folders**

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

    Comma-separated list of combined folder identifiers which
    are loaded into the FILES object.

    A combined folder identifier looks like this:
    \[storageUid\]:\[folderIdentifier\].

    The first part is the UID of the storage and the second
    part the identifier of the folder. The identifier of the
    folder is often equivalent to the relative path of the
    folder.

    The property folders has the option `recursive` to get
    files recursively.

    **Example:**

    ```typoscript
    page.10 = FILES
    page.10.folders = 2:mypics/,4:myimages/
    ```

    Example for option `recursive`:

    **EXT:site_package/Configuration/Sets/Main/setup.typoscript**

    ```typoscript
    filecollection = FILES
    filecollection {
      folders = 1:images/
      folders.recursive = 1

      renderObj = IMAGE
      renderObj {
        file.import.data = file:current:uid
      }
    }

    ```

### sorting {#cobj-files-sorting}

-   **sorting**

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

    Name of the field, which should be used to sort the files.

### sorting.direction {#cobj-files-sorting-direction}

-   **sorting.direction**

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

    The direction, in which the
    files should be sorted. Possible values are "asc" for ascending and
    "desc" for descending.

### begin {#cobj-files-begin}

-   **begin**

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

    The first item to return. If not set (default), items beginning
    with the first one are returned.

### maxItems {#cobj-files-maxitems}

-   **maxItems**

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

    Maximum number of items to return. If not set (default), all items
    are returned. If [begin](https://docs.typo3.org/permalink/t3tsref:cobj-files-begin@main) and [maxItems](https://docs.typo3.org/permalink/t3tsref:cobj-files-maxitems@main)
    together exceed the number of available items, no items beyond the
    last available item will be returned.

### renderObj {#cobj-files-renderobj}

-   **renderObj**

    -   *Type:* [cObject](https://docs.typo3.org/permalink/t3tsref:data-type-cobject@main) [+optionSplit](https://docs.typo3.org/permalink/t3tsref:optionsplit@main)

    The cObject used for rendering the files. It is executed
    once for every file. Note that during each execution you can
    find information about the current file using the getText
    property "file" [file](https://docs.typo3.org/permalink/t3tsref:data-type-gettext-file@main) with the "current" keyword.
    Look there to find out which properties of the file are available.

    **Example:**

    **EXT:site_package/Configuration/Sets/Main/setup.typoscript**

    ```typoscript
    page.10.renderObj = TEXT
    page.10.renderObj {
      stdWrap.data = file:current:size
      stdWrap.wrap = <p>File size:<strong>|</strong></p>
    }

    ```

    This returns the size of the current file.

### stdWrap {#cobj-files-stdwrap}

-   **stdWrap**

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

## Special key: "references" {#cobj-files-references-table}

-   **references.table**

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

    The table name of the table having the file field.

### references.uid {#cobj-files-references-uid}

-   **references.uid**

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

    The UID of the record from which to fetch the referenced files.

### references.fieldName {#cobj-files-references-fieldname}

-   **references.fieldName**

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

    Field name of the file field in the table.

## Examples {#cobj-files-examples}

### Usage with files {#cobj-files-examples-files}

In this example, we first load files using several of the methods
explained above (using sys_file UIDs, collection UIDs, and folders).
Then we use the [TEXT](https://docs.typo3.org/permalink/t3tsref:cobj-text@main) cObject as [renderObj](https://docs.typo3.org/permalink/t3tsref:cobj-files-renderobj@main)
to output the file size of all files that were found:

**EXT:site_package/Configuration/Sets/Main/setup.typoscript**

```typoscript
page.10 = FILES

page.10.files = 12,15,16
page.10.collections = 2,9
page.10.folders = 1:mypics/

page.10.renderObj = TEXT
page.10.renderObj {
  stdWrap.data = file:current:size
  stdWrap.wrap = <p>File size: <strong>|</strong></p>
}

```

### Usage with references {#cobj-files-examples-references}

In this second example, we use "references" to get the images related
to a given page (in this case, the current page). We start with the
first image and return up to five images. Each image is then rendered
as an [IMAGE](https://docs.typo3.org/permalink/t3tsref:cobj-image@main) cObject with some meta data coming from
the file itself or from the reference to it (title):

**EXT:site_package/Configuration/Sets/Main/setup.typoscript**

```typoscript
page.20 = FILES
page.20 {
  references {
    table = pages
    uid.data = page:uid
    fieldName = media
  }

  begin = 0
  maxItems = 5

  renderObj = IMAGE
  renderObj {
    file.import.dataWrap = {file:current:storage}:{file:current:identifier}
    altText.data = file:current:title
    wrap = <div class="slide">|</div>
  }
  stdWrap.wrap = <div class="carousel">|</div>
}

```

### Usage with sliding {#cobj-files-examples-sliding}

One usual feature is to use images attached to pages and use
them up and down the page tree, a process called "sliding".

**EXT:site_package/Configuration/Sets/Main/setup.typoscript**

```typoscript
lib.banner = FILES
lib.banner {
  references {
    data = levelmedia: -1, slide
  }

  renderObj = IMAGE
  renderObj {
    file.import.dataWrap = {file:current:storage}:{file:current:identifier}
    altText.data = file:current:title
    wrap = <div class="banner">|</div>
  }
}

```