Attention

TYPO3 v10 has reached end-of-life as of April 30th 2023 and is no longer being maintained. Use the version switcher on the top left of this page to select documentation for a supported version of TYPO3.

Need more time before upgrading? You can purchase Extended Long Term Support (ELTS) for TYPO3 v10 here: TYPO3 ELTS.

Assets (CSS, JavaScript, Media)

The TYPO3 component responsible for rendering the HTML and adding assets to a TYPO3 frontend or backend page is called PageRenderer.

The PageRenderer collects all assets to be rendered, takes care of options such as concatenation or compression and finally generates the necessary tags.

There are multiple ways to add assets to the PageRenderer in TYPO3. For configuration options via TypoScript (usually used for the main theme files), see the TypoScript reference. In extensions, both directly using the PageRenderer as well as using the more convenient AssetCollector is possible.

Note

The AssetCollector is available since TYPO3 10.3.

AssetCollector

The AssetCollector is a concept to allow custom CSS/JS code, inline or external, to be added multiple times in e.g. a Fluid template (via <f:asset.script> or <f:asset.css> ViewHelpers) but rendered only once in the output.

It supports best practices for optimizing page performance by having a "priority" flag to either move the asset to the <head> section (useful for CSS in above-the-fold concepts) or the bottom of the <body> tag.

The AssetCollector helps to work with content elements as components, effectively reducing the CSS to be loaded. It also incorporates the HTTP/2 power, where it is not relevant to have all files compressed and concatenated into one file.

The AssetCollector is implemented as a singleton and should slowly replace the various other existing options in TypoScript.

The AssetCollector also collects information about "imagesOnPage", which can be used in cached and non-cached components.

The API

  • \TYPO3\CMS\Core\Page\AssetCollector::addJavaScript(string $identifier, string $source, array $attributes, array $options = []): self

  • \TYPO3\CMS\Core\Page\AssetCollector::addInlineJavaScript(string $identifier, string $source, array $attributes, array $options = []): self

  • \TYPO3\CMS\Core\Page\AssetCollector::addStyleSheet(string $identifier, string $source, array $attributes, array $options = []): self

  • \TYPO3\CMS\Core\Page\AssetCollector::addInlineStyleSheet(string $identifier, string $source, array $attributes, array $options = []): self

  • \TYPO3\CMS\Core\Page\AssetCollector::addMedia(string $fileName, array $additionalInformation): self

  • \TYPO3\CMS\Core\Page\AssetCollector::removeJavaScript(string $identifier): self

  • \TYPO3\CMS\Core\Page\AssetCollector::removeInlineJavaScript(string $identifier): self

  • \TYPO3\CMS\Core\Page\AssetCollector::removeStyleSheet(string $identifier): self

  • \TYPO3\CMS\Core\Page\AssetCollector::removeInlineStyleSheet(string $identifier): self

  • \TYPO3\CMS\Core\Page\AssetCollector::removeMedia(string $identifier): self

  • \TYPO3\CMS\Core\Page\AssetCollector::getJavaScripts(?bool $priority = null): array

  • \TYPO3\CMS\Core\Page\AssetCollector::getInlineJavaScripts(?bool $priority = null): array

  • \TYPO3\CMS\Core\Page\AssetCollector::getStyleSheets(?bool $priority = null): array

  • \TYPO3\CMS\Core\Page\AssetCollector::getInlineStyleSheets(?bool $priority = null): array

  • \TYPO3\CMS\Core\Page\AssetCollector::getMedia(): array

Note

If the same asset is registered multiple times using different attributes or options, both sets are merged. If the same attributes or options are given with different values, those registered last will overwrite the existing ones.

ViewHelpers

There are also two ViewHelpers, the f:asset.css and the f:asset.script ViewHelper which use the AssetCollector API.

Rendering order

Currently, CSS and JavaScript registered with the AssetCollector will be rendered after their PageRenderer counterparts. The order is:

  • <head>

  • page.includeJSLibs.forceOnTop

  • page.includeJSLibs

  • page.includeJS.forceOnTop

  • page.includeJS

  • AssetCollector::addJavaScript() with 'priority'

  • page.jsInline

  • AssetCollector::addInlineJavaScript() with 'priority'

  • </head>

  • page.includeJSFooterlibs.forceOnTop

  • page.includeJSFooterlibs

  • page.includeJSFooter.forceOnTop

  • page.includeJSFooter

  • AssetCollector::addJavaScript()

  • page.jsFooterInline

  • AssetCollector::addInlineJavaScript()

Note

JavaScript registered with AssetCollector is not affected by config.moveJsFromHeaderToFooter.

Examples

Add a JavaScript file to the collector with script attribute data-foo="bar":

GeneralUtility::makeInstance(AssetCollector::class)
   ->addJavaScript('my_ext_foo', 'EXT:my_ext/Resources/Public/JavaScript/foo.js', ['data-foo' => 'bar']);

Add a JavaScript file to the collector with script attribute data-foo="bar" and priority which means rendering before other script tags:

GeneralUtility::makeInstance(AssetCollector::class)
   ->addJavaScript('my_ext_foo', 'EXT:my_ext/Resources/Public/JavaScript/foo.js', ['data-foo' => 'bar'], ['priority' => true]);

Add a JavaScript file to the collector with type="module" (by default, no type= is output for JavaScript):

GeneralUtility::makeInstance(AssetCollector::class)
   ->addJavaScript('my_ext_foo', 'EXT:my_ext/Resources/Public/JavaScript/foo.js', ['type' => 'module']);

Events

There are two events available that allow additional adjusting of assets: