File List

Classification: file_list
Version: main
Language: en
Description: This extension provides a frontend plugin which shows a list of files and folders in a specified directory on the file system (comparable to Apache directory listing) or using more advanced FAL selectors (categories, collection of files, ...). This extension may also be used for creating image galleries.
Keywords: list, file, directory, files, directories, gallery, bootstrap
Copyright: 2008-2026
Author: Xavier Perseguers
Email: xavier@causal.ch
License: This document is published under the Open Publication License available from https://www.opencontent.org/openpub/
Rendered: Fri, 13 Mar 2026 16:02:09 +0000

The content of this document is related to TYPO3, a GNU/GPL CMS/Framework available from www.typo3.org.

Table of Contents

Introduction

What does it do?

This extension provides a frontend plugin which shows a list of files and folders in a specified directory on the file system or using more advanced FAL selectors such as categories or collections of files.

You can sort the files in this directory over the Backend by file name, title, description, size or creation/modification date. The files will be sorted by file name by default.

There is also an option to display files as "new" (with a localized text after the name).

Hint

This plugin takes file restrictions into account ("Is Visible" and "Access Groups" in the metadata of a single file) if you are using them.

Hint

As you may figure it out, this plugin could easily turn a list of images (and possibly subfolders) into an easy-to-use image gallery. You probably will not be in need of any other extension for that purpose.

Be sure to have a look and consider installing extension "image_autoresize" available in TER if you plan to seriously use TYPO3 for storing a large collection of images.

Note

Screenshots

Information such as titles and descriptions are those you may populate in TYPO3 Backend, using FAL.

Simple list

Description and thumbnail

Hint

You may use extension "extractor" available in TER to automatically extract and populate metadata when you upload assets to your website.

Icons

Icons have been created by:

To Uyen
Cristian Bogdan Rosu
Erik Ragnar Eliasson
Laurent Baumann

Users manual

To add the plugin on a page, you can insert it as "plugin".

Configuration

Note

The path will always be checked against any configured "root" (please read TypoScript configuration), allowing the plugin to be used in a multi-site installation without risking an editor from showing files from another website.

Administrator manual

This plugin comes with a static TypoScript which should be added to your template:

Configuration over TypoScript

plugin.tx_filelist.settings

This table is an overview of the main keys in the plugin configuration plugin.tx_filelist.settings:

Properties

Property	Data type	stdWrap	Default
path	string	yes	empty
root	string, array	yes	empty
dateFormat	string	yes	"d.m.Y H:i"
fileIconRootPath	string	yes	"EXT:file_list/Resources/Public/Icons/Files/"
newDurationMaxSubfolders	integer	yes	3
name	string	no	empty
extension	string	no	empty

Property details

path

plugin.tx_filelist.settings.path = file:1:/path/to/folder/

Root folder for the plugin.

root

plugin.tx_filelist.settings.root = file:1:/path/to/folder/

plugin.tx_filelist.settings.root {
    10 = file:1:/path/to/folder/
    20 = file:2:/some/other/
}

Allowed root folder or array of allowed root folders. This forces the folder of all plugins to be within these folders' hierarchy.

dateFormat

plugin.tx_filelist.settings.dateFormat = d.m.Y H:i:s

Format used by the default templates to show file's creation date.

fileIconRootPath

plugin.tx_filelist.settings.fileIconRootPath = EXT:<extension-key>/Resources/Public/Icons/FileTypes/

Path to the directory containing icons for file types (either relative to site root or prefixed with an extension name).

newDurationMaxSubfolders

plugin.tx_filelist.settings.newDurationMaxSubfolders = 3

Number of subdirectory levels to check for new files (in order to show a "new" badge for folders).

extension.category.<name>

plugin.tx_filelist.settings.extension.category.<name> = extension1, extension2

Comma-separated list of extensions belonging to the category "name".

When a file link is rendered, the extension searches for a dedicated icon (e.g., docx.png or docx.gif in directory fileIconRootPath. If this dedicated icon is not found, the category icon will be used instead (category_name.png).

Default are categories "archive", "document", "flash", "image", "sound", "source" and "video" defined with all common corresponding file extensions.

extension.remap.<extension>

plugin.tx_filelist.settings.extension.remap.<extension1> = extension2

Remapping of extensions before falling back to the category icon. If "docx" is remapped to "doc" with

extension.remap.docx = doc

and a ".docx" file is encountered when rendering the file link, a docx.png or docx.gif icon will be searched for.

If not found, a doc.png or doc.gif icon will be searched for to be used instead. And if not found, the category icon will be used as a fallback option.

Best practices

This chapter describes some best practice concepts.

Integration with TypoScript

This page gives you some examples which you can use for integrating EXT:file_list into a website.

Add file_list by TypoScript

If EXT:file_list should be integrated by using TypoScript only, you can use this code snippet:

lib.filelist = USER
lib.filelist {
    userFunc = TYPO3\CMS\Extbase\Core\Bootstrap->run
    extensionName = FileList
    vendorName = Causal
    pluginName = Filelist

    switchableControllerActions {
        File {
            1 = list
        }
    }

    settings < plugin.tx_filelist.settings
    settings {
        path = file:1:/path/to/directory/
        mode = FOLDER
        includeSubfolders = 1
        templateLayout = ThumbnailDescription
    }
}

Now you can use the object lib.filelist.

Image gallery (example)

This chapter is an example on how you may extend this extension to be used as an image gallery.

Create a dedicated extension

Create an extension skeleton (e.g., my_gallery) under typo3conf/ext/my_gallery/. You basically need two files:

ext_emconf.php (copy and adapt from another extension);
ext_icon.png.

Now we need to register an additional layout for the file list plugin, as described in chapter Additional Template Layouts.

Create file ext_localconf.php:

<?php
defined('TYPO3') || die();

$boot = function (string $_EXTKEY) {

    /* ===========================================================================
        Register an "image gallery" layout
    =========================================================================== */
    $GLOBALS['TYPO3_CONF_VARS']['EXT']['file_list']['templateLayouts'][] = [
        'Image Gallery', // You may use a LLL:EXT: label reference here of course!
        'MyGallery',
    ];

};

$boot('<your_extension_key>');
unset($boot);

We could add the few lines of TypoScript to our existing template but let do that with a staticTS, as usual.

Create files ext_tables.php:

<?php
defined('TYPO3') || die();

$boot = function (string $_EXTKEY) {

    /* ===========================================================================
        Register default TypoScript
    =========================================================================== */
    \TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addStaticFile(
        $_EXTKEY,
        'Configuration/TypoScript/',
        'My Gallery'
    );

};

$boot('<your_extension_key>');
unset($boot);

and Configuration/TypoScript/setup.txt:

plugin.tx_filelist {
    view {
        partialRootPaths.100 = EXT:my_gallery/Resources/Private/Partials/
    }
}

Create the HTML of your gallery

Yes, we are already nearly ready! Now we just need to create the HTML Fluid template to be used with key "MyGallery".

Create file Resources/Private/Partials/MyGallery.html:

<html xmlns="http://www.w3.org/1999/xhtml" lang="en"
      xmlns:f="http://typo3.org/ns/TYPO3/Fluid/ViewHelpers"
      xmlns:fl="http://typo3.org/ns/Causal/FileList/ViewHelpers"
      data-namespace-typo3-fluid="true">

    <f:for each="{files}" as="file">

        <figure>
            <a href="{f:uri.image(image: file, maxWidth: 1200, maxHeight: 800)}"
                rel="lightbox[gallery_{data.uid}]"
                title="{file.properties.description}">

                <fl:thumbnail image="{file}" width="256c" height="256c" />
            </a>
            <figcaption>
                <f:if condition="{file.properties.description}">
                    <f:then>{file.properties.description}</f:then>
                    <f:else>
                        <f:if condition="{file.properties.title}">
                            <f:then>{file.properties.title}</f:then>
                            <f:else>{file.name}</f:else>
                        </f:if>
                    </f:else>
                </f:if>
            </figcaption>
        </figure>

    </f:for>

</html>

This is just an example of course! But it shows you how to get a lightbox-enabled gallery of images with the FAL description or title (or even file name) as fallback.

Have fun!

Note

By iterating over {folders} in addition to {files} your gallery would support nested collections of images, based on folders. Just like that.

Hint

If you need to deal with a large list of images, you probably will want to paginate it and you may find the Paginate ViewHelper from Fluid Powered TYPO3 useful...

Developer manual

Extend FlexForm

Following fields of the plugin configuration may be extended without overriding the complete FlexForm configuration.

Additional Template Layouts

By default this extension provides two different "layouts" available in a drop-down list:

If you need other options, you may register them easily using following code:

$GLOBALS['TYPO3_CONF_VARS']['EXT']['file_list']['templateLayouts'][] = [
    'my label',
    'my value'
];

You can then access the variable in your template with {settings.templateLayout} and use it for a condition or whatever.

Known problems

Note

Please use the extension's bug tracker on GitHub to report bugs: https://github.com/xperseguers/t3ext-file_list/issues

File List

Introduction

What does it do?

Screenshots

Simple list

Description and thumbnail

Icons

Users manual

Configuration

Administrator manual

Configuration over TypoScript

plugin.tx_filelist.settings

Properties

Property details

path

root

dateFormat

fileIconRootPath

newDurationMaxSubfolders

extension.category.<name>

extension.remap.<extension>

Best practices

Integration with TypoScript

Add file_list by TypoScript

Image gallery (example)

Create a dedicated extension

Create the HTML of your gallery

Developer manual

Extend FlexForm

Additional Template Layouts

Known problems

Links

How to contribute

Contribution rules

File List

Introduction

What does it do?

Screenshots

Simple list

Breadcrumb menu

Description and thumbnail

Icons

Users manual

Configuration

Administrator manual

Configuration over TypoScript

plugin.tx_filelist.settings

Properties

Property details

path

root

dateFormat

fileIconRootPath

newDurationMaxSubfolders

extension.category.<name>

extension.remap.<extension>

Best practices

Integration with TypoScript

Add file_list by TypoScript

Image gallery (example)

Create a dedicated extension

Create the HTML of your gallery

Developer manual

Extend FlexForm

Additional Template Layouts

Known problems

Links

How to contribute

Contribution rules