Add CSS and JavaScript in TYPO3: 11 Methods Compared

Are you looking for reliable ways to add CSS and JavaScript assets in TYPO3?

As a TYPO3 integrator, developer, or administrator, you’ll often need to include custom stylesheets or third-party JavaScript libraries into a TYPO3 instance, whether for templates, extensions, or specific pages.

In this blog, you’ll learn all 11 proven methods to add internal and external CSS/JS assets into TYPO3, clearly explained and ready to apply in real projects.

TYPO3 is a flexible and extensible open-source CMS, designed to handle a wide range of frontend requirements. Depending on the use case, legacy systems, modern templates, or extension development, TYPO3 provides multiple ways to integrate frontend assets cleanly and predictably for efficient TYPO3 development. 

That flexibility also makes it possible to introduce new development capabilities through solutions such as the AI Foundation for TYPO3, while keeping AI providers, permissions, and workflows centrally managed.

Let’s walk through each method and understand where it fits best.

Short answer: In TYPO3 v13.4 LTS and v14, add CSS and JavaScript with the Fluid ViewHelpers <f:asset.css> and <f:asset.script> in templates, and with the AssetCollector API in extension code. TypoScript includeCSS and includeJS still work for global files. Avoid $GLOBALS['TSFE']: TYPO3 v14 removed it.

Key takeaways

• Templates: use <f:asset.css> and <f:asset.script> (since v10.3). TYPO3 renders each identifier only once.
• Extensions: call addStyleSheet() or addJavaScript() on the AssetCollector; priority moves JavaScript into the <head>.
• TypoScript includeCSS, includeJS, headerData and footerData still work in v14, but v14 no longer concatenates or compresses files.
• additionalHeaderData and additionalFooterData on TSFE are gone in v14; use PageRenderer::addHeaderData() or addFooterData().
• Fluid HeaderAssets and FooterAssets sections are deprecated since v14.0 and will be removed in v15.0.
• With a Content Security Policy, mark inline code with csp (v14.2+) or useNonce (v13).

Tested with / valid for: TYPO3 v13.4 LTS and v14.3 LTS (code checked against the official TYPO3 documentation)
Updated: November 2026

All 11 methods in this guide still run in TYPO3 v13.4 LTS. In TYPO3 v14, the two TSFE methods are removed and the Fluid HeaderAssets/FooterAssets sections are deprecated; everything else keeps working.

TYPO3 v14.3 LTS was released on 21 April 2026. The current releases are 14.3.10 and 13.4.37, and both need PHP 8.2 or higher (source: get.typo3.org).

Recommendation: for new TYPO3 v13 or v14 work, use the f:asset ViewHelpers in templates and the AssetCollector in PHP. Keep existing TypoScript includes for global files, and replace TSFE and HeaderAssets code before or during your v14 upgrade.

Running a purchased T3Planet template and want custom CSS or JavaScript built into it? Our TYPO3 template customization service adapts look, feel and functionality of the template for you.

Related reading: our 45+ TypoScript tips and tricks and the TypoScript conditions cheatsheet help when you load assets per page or per site.

Fluid Asset ViewHelpers are the recommended way to add CSS and JavaScript from a Fluid template in TYPO3 v13 and v14. They were introduced in TYPO3 v10.3 together with the AssetCollector and work in every version since.

Using <f:asset.css /> and <f:asset.script />, assets can be registered directly within Fluid templates while maintaining predictable rendering and better control.

This approach is well-suited for modern TYPO3 projects where assets are tightly coupled with template logic and should follow TYPO3’s recommended frontend architecture.

<f:asset.css identifier="yourIdentifier" href="EXT:yourext/Resources/Public/Css/myCustom.css" />
<f:asset.css identifier="yourIdentifier">
  .myBlock { display: block }
</f:asset.css>

<f:asset.script identifier="yourIdentifier" src="EXT:yourext/Resources/Public/JavaScript/myCustom.js" />
<f:asset.script identifier="yourIdentifier">
  alert('hello world');
</f:asset.script>

Each asset needs a unique identifier; TYPO3 renders an asset with the same identifier only once. Add priority="1" to place a script in the <head>, and defer or async for scripts that should not block rendering. On sites with a Content Security Policy, mark inline code with csp="1" (TYPO3 v14.2 and later) or useNonce="1" (TYPO3 v13).

For more Fluid patterns, see our TYPO3 Fluid guide with 50+ ViewHelper tips.

Reference: View Document

The Fluid sections HeaderAssets and FooterAssets still work in TYPO3 v13, but TYPO3 v14.0 deprecated their auto-rendering and TYPO3 v15.0 will remove it. Since TYPO3 v8.6, Extbase renders these sections of an action template into the page head or footer.

This method is useful when assets need to be injected explicitly into the <head> or at the end of the <body>.

Migrate to <f:asset.css> and <f:asset.script>. For markup those ViewHelpers cannot produce, such as preconnect tags, TYPO3 v14 adds <f:page.headerData> and <f:page.footerData>.

<f:section name="HeaderAssets">
   <!-- Write down anything which you want to add into <head> tag -->
</f:section>

<f:section name="FooterAssets">
   <!-- Write down anything which you want to add into </body> tag -->
   <script async src="//yourdomain.com/your.js"></script>
</f:section>

Reference: View Document, Deprecation in v14.0

page.headerData is still supported in TYPO3 v13 and v14 and is one of the traditional TypoScript-based methods to inject CSS or JavaScript into the <head> section of a TYPO3 page.

It allows assets to be added globally or conditionally based on page IDs.

TypoScript property names are case-sensitive: write headerData, not HeaderData. The TypoScript reference recommends includeCSS and includeJS for files and headerData for other markup, such as meta or verification tags.

page.headerData.99 = TEXT
page.headerData.99.value = <script async src="//yourdomain.com/your.js"></script>

page.footerData works similarly to page.headerData and is still supported in TYPO3 v14, but outputs assets just before the closing </body> tag.

This is often preferred for JavaScript files to reduce render-blocking and improve perceived performance.

Like headerData, this approach is mainly relevant for older TYPO3 installations.

page.footerData.99 = TEXT
page.footerData.99.value = <script async src="//yourdomain.com/your.js"></script>

includeJS is one of the most widely used TypoScript methods for adding JavaScript files to TYPO3 templates.

It supports loading scripts in the header, footer, or as libraries, depending on configuration.

It is still supported in TYPO3 v13 and v14. Since TYPO3 v14.0, the Core no longer concatenates or compresses files added this way, and the file properties external, disableCompression and excludeFromConcatenation no longer exist. Use includeJSFooter to load a file before </body>.

page.includeJS {
   yourIdentifier = EXT:yourext/Resources/Public/JavaScript/myCustom.js
}

Tips:
You can use config.moveJsFromHeaderToFooter to shift scripts for better performance. JavaScript registered with the AssetCollector is not affected by this option.

If you need to include inline JavaScript, TYPO3 provides jsInline and jsFooterInline. This allows you to write JavaScript code directly without referencing an external file.

Inline scripts should be used sparingly, as they are harder to cache and maintain compared to file-based assets.

page.jsInline {
   10 = TEXT
   10.value = console.log('Hello from TYPO3');
}

Like the other page properties, jsInline takes numbered content objects such as TEXT. It still works in TYPO3 v13 and v14.

includeCSS allows you to register CSS files via TypoScript and include them in the <head> section. This method is commonly found in older TYPO3 templates and legacy integrations.

For modern projects, Fluid Asset ViewHelpers or AssetCollector are generally preferred.

page.includeCSS {
   yourIdentifier = EXT:yourext/Resources/Public/Css/myCustom.css
}

cssInline enables you to define inline CSS directly through TypoScript.
This can be useful for small, dynamic styles but should not replace structured, file-based CSS in larger projects.

page.cssInline {
   10 = TEXT
   10.value = h1 {margin:15px;}
}

For extension developers working with Extbase, additionalFooterData allows JavaScript to be injected dynamically from a controller.

This method provides flexibility but bypasses modern asset management workflows.

TYPO3 v13 marked this property as internal, and TYPO3 v14.0 removed $GLOBALS['TSFE'] completely. The code below only runs up to TYPO3 v13. In v14, use the PageRenderer instead, or AssetCollector for script files.

$GLOBALS['TSFE']->additionalFooterData['yourIdentifier'] =
   '<script async src="//yourdomain.com/your.js"></script>';

TYPO3 v14 replacement:

$pageRenderer = GeneralUtility::makeInstance(PageRenderer::class);
$pageRenderer->addFooterData('<script async src="//yourdomain.com/your.js"></script>');

Reference: Breaking change #107831 in TYPO3 v14.0

Similar to additionalFooterData, this method injects assets into the <head> section from an Extbase controller.

It works up to TYPO3 v13 only and is not recommended for modern TYPO3 extensions. TYPO3 v14.0 removed $GLOBALS['TSFE']; the official migration is PageRenderer::addHeaderData().

$GLOBALS['TSFE']->additionalHeaderData['yourIdentifier'] =
   '<script async src="//yourdomain.com/your.js"></script>';

TYPO3 v14 replacement:

$pageRenderer = GeneralUtility::makeInstance(PageRenderer::class);
$pageRenderer->addHeaderData('<script async src="//yourdomain.com/your.js"></script>');

Upgrading to TYPO3 v14?
The free Upgrade Playbook for TYPO3 (18 pages plus an Excel worksheet) plans your upgrade in four phases and keeps the site secure afterwards with security bulletins, ELTS and a maintenance calendar.
Get the free Upgrade Playbook

AssetCollector is the recommended way to add CSS and JavaScript from PHP code in TYPO3 v13 and v14. It was introduced in TYPO3 v10.3 and is also the API behind the f:asset ViewHelpers.

It provides centralized asset handling, priority control, and avoids duplication across templates and extensions.

This is the preferred approach for modern TYPO3 development.

GeneralUtility::makeInstance(AssetCollector::class)

  ->addJavaScript(

      'yourIdentifier',

      'EXT:yourext/Resources/Public/JavaScript/myCustom.js',

      ['data-foo' => 'bar']

  );

Pass ['priority' => true] as fourth argument to render a script in the <head>, or ['type' => 'module'] as attribute for an ES module. Instead of makeInstance(), you can also inject AssetCollector via the constructor, as the official documentation shows. The external option was removed in TYPO3 v14.0, and from v14.2 the option csp replaces useNonce.

AssetCollector offers a rich API for managing assets throughout the request lifecycle and should be the default choice for new extensions.

AssetCollector::addInlineJavaScript()

AssetCollector::addStyleSheet()

AssetCollector::addInlineStyleSheet()

AssetCollector::addMedia()

AssetCollector::removeJavaScript()

AssetCollector::removeInlineJavaScript()

AssetCollector::removeStyleSheet()

AssetCollector::removeInlineStyleSheet()

AssetCollector::removeMedia()

AssetCollector::getJavaScripts()

AssetCollector::getInlineJavaScripts()

AssetCollector::getStyleSheets()

AssetCollector::getInlineStyleSheets()

AssetCollector::getMedia()

AssetCollector::hasJavaScript()

AssetCollector::hasStyleSheet()

Reference: View Document

TYPO3 supports multiple ways to include CSS and JavaScript, but the recommended approach changes by TYPO3 version. The overview below summarizes which methods are preferred and which should be treated as legacy.

This section is a quick reference and does not replace the detailed explanations that follow.

TYPO3 v14 / v13 / v12

Recommended

• Fluid Asset ViewHelpers (<f:asset.css />, <f:asset.script />)
• Extbase AssetCollector (centralized asset handling)

Why this matters

• Native, modern API aligned with TYPO3 core direction
• Better performance and dependency handling
• Cleaner separation of concerns (no inline clutter)

Legacy / Avoid for new projects

• TypoScript HeaderData / FooterData
• additionalHeaderData / additionalFooterData

TYPO3 v11 / v10

Recommended

• Extbase AssetCollector
• Fluid Asset ViewHelpers

Acceptable (legacy but supported)

• Fluid HeaderAssets / FooterAssets
• TypoScript includeJS / includeCSS

TYPO3 v9 / v8

Commonly used

• Fluid HeaderAssets / FooterAssets
• TypoScript includeJS / includeCSS
• Inline TypoScript (jsInline, cssInline)

Consider

• Planning migration to AssetCollector when upgrading to newer TYPO3 versions

TYPO3 v7 and Earlier

Legacy only

• TypoScript HeaderData / FooterData
• Inline CSS/JS via TypoScript or PHP

Note

• These approaches are not recommended for modern TYPO3 projects and should be refactored during upgrades.

Important Reminder

• Avoid mixing multiple asset-inclusion methods within the same page or extension.
• Choose one primary approach per TYPO3 version for predictable rendering and easier TYPO3 support & maintenance. 

The sections below explain all 11 methods in detail, including their use cases and limitations.

TYPO3 renders TypoScript (PageRenderer) assets first and AssetCollector assets after them. JavaScript with priority goes into the <head>, all other AssetCollector JavaScript goes before </body>. CSS is always rendered in the <head>, grouped by priority.

This order is documented for TYPO3 v10.3 up to v14.3 (TYPO3 Explained: Assets):

<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()

With a Content Security Policy (CSP), the browser blocks inline scripts and styles that the policy does not allow. Mark inline assets for CSP, and TYPO3 adds the matching nonce or hash for you.

• Enable CSP in the frontend: set the feature flag security.frontend.enforceContentSecurityPolicy (or reportContentSecurityPolicy for report-only mode), or set the disposition in the site's csp.yaml.
• TYPO3 v13: use useNonce="1" on f:asset.script and f:asset.css, or ['useNonce' => true] in the AssetCollector.
• TYPO3 v14.2 and later: use csp="1" or ['csp' => true]. useNonce still works but logs a deprecation and will be removed in v15.0. For external files, csp is on by default.
• Hashes instead of nonces (v14.2+): a nonce changes on every request, so full responses cannot be cached by a reverse proxy. With useHash: true and useNonce: false under behavior in csp.yaml, TYPO3 sends hash sources and pages stay cacheable.

<f:asset.script identifier="greeting" csp="1">
   console.log('Hello');
</f:asset.script>

Sources: TYPO3 Explained: Content Security Policy, Deprecation #100887

How CSS and JavaScript are added in TYPO3 does not only affect functionality, it also impacts page performance, rendering behavior, and Core Web Vitals.

Understanding these implications helps you avoid common performance bottlenecks, especially in modern TYPO3 projects.

Header vs Footer Loading

• CSS is usually loaded in the <head> to prevent layout shifts
• JavaScript loaded in the <head> can block rendering if not handled carefully
• Footer-loaded JavaScript reduces render-blocking and improves perceived speed

TYPO3 provides multiple ways to control where and when assets are rendered. Choosing the right method is key for performance-sensitive pages.

Render-Blocking Risks

• Inline or header-based JavaScript can delay page rendering
• Loading unnecessary assets globally increases page weight
• Mixing multiple asset inclusion methods can lead to duplicate or unordered output

Modern approaches such as AssetCollector help avoid these issues by managing priorities and render order more predictably.

Why AssetCollector Helps Performance

• Centralized asset management
• Better control over load order and priority
• Avoids accidental duplication across templates and extensions
• Easier to debug asset-related issues

For TYPO3 v10 and above, AssetCollector is generally the safest choice for performance-aware projects.

What Changed for Performance in TYPO3 v14?

TYPO3 v14 no longer concatenates or compresses frontend CSS and JavaScript. The TypoScript options config.concatenateCss, config.concatenateJs, config.compressCss and config.compressJs were removed in v14.0 (Breaking change #108055).

The official alternatives are a build tool such as Vite or Webpack, compression by the web server, HTTP/2 or HTTP/3, and a CDN for static files. Our overview of free TYPO3 CDN extensions lists options for the last point.

Performance Best Practices (Quick Checklist)

• Load JavaScript in the footer whenever possible, or add defer to <f:asset.script>
• Avoid inline assets unless they are truly required
• Do not inject the same asset via multiple methods
• Regularly audit frontend output for unused CSS or JS

These practices help keep TYPO3 projects fast, maintainable, and TYPO3 upgrade-friendly.

Even though TYPO3 offers multiple ways to include frontend assets, misusing them can lead to performance issues, unpredictable behavior, or upgrade problems. Avoid the common mistakes below to keep your TYPO3 project clean and maintainable.

1. Using Legacy TypoScript Methods in Modern TYPO3 Versions

What goes wrong

• Methods like HeaderData, FooterData, or old includeJS patterns are used in TYPO3 v10+
• Asset loading becomes harder to control and debug

Why it’s a problem

• These approaches were designed for older TYPO3 architectures
• They increase technical debt and complicate future upgrades

What to do instead

• Prefer Fluid Asset ViewHelpers or AssetCollector in modern TYPO3 projects

2. Mixing Multiple Asset Injection Methods on the Same Page

What goes wrong

• CSS or JS is added via TypoScript, Fluid, and PHP simultaneously
• Assets appear multiple times or in unexpected order

Why it’s a problem

• Render order becomes unpredictable
• Debugging frontend issues becomes significantly harder

What to do instead

• Choose one primary asset inclusion method per page or extension
• Keep asset handling consistent across the project

3. Relying Too Heavily on Inline JavaScript or CSS

What goes wrong

• Inline JS or CSS is added for convenience
• Logic and styling become scattered and hard to maintain

Why it’s a problem

• Inline assets are harder to cache
• They can negatively affect performance and readability

What to do instead

• Use file-based assets whenever possible
• Reserve inline code for truly dynamic or minimal use cases

4. Loading Assets Globally When They Are Only Needed on Specific Pages

What goes wrong

• CSS or JS is included site-wide for a feature used on only a few pages

Why it’s a problem

• Increases page weight unnecessarily
• Affects performance across the entire site

What to do instead

• Scope assets to templates, pages, or extensions where they are required

5. Ignoring Render Order and Dependencies

What goes wrong

• JavaScript executes before the DOM or required libraries are available
• CSS overrides do not apply as expected

Why it’s a problem

• Leads to broken functionality or layout issues
• Often mistaken for “random” frontend bugs

What to do instead

• Be aware of TYPO3’s asset rendering order
• Use modern methods that support priority and dependency handling

6. Skipping Cleanup During TYPO3 Upgrades

What goes wrong

• Old asset inclusion methods remain after upgrading TYPO3
• Multiple legacy patterns accumulate over time

Why it’s a problem

• Increases maintenance effort
• Makes future debugging and optimization harder

What to do instead

• Review asset inclusion methods during upgrades
• Gradually replace legacy approaches with modern ones

Thanks for reading this guide. We hope it helped you clearly understand the different ways to add CSS and JavaScript assets in TYPO3, and when to use each approach in real projects.

TYPO3 offers multiple valid methods for asset integration, and the right choice always depends on your use case, TYPO3 version, and project structure. If you’ve worked with any of these methods before, feel free to share your experience in the comments.

If you’re curious about how AI is being applied in the ecosystem, take a look at the AI Universe for TYPO3, where practical TYPO3 workflows meet intelligent automation.

And for teams looking to streamline content creation, code generation, and optimization directly inside TYPO3, the T3AI - AI assistant provides a focused, all-in-one solution.

Build clean, maintainable TYPO3 projects with the right asset strategy and improved TYPO3 accessibility.

Free TYPO3 guides for your team
Seven free playbooks for TYPO3 teams and agencies, each a PDF with Excel worksheets: upgrade, accessibility, relaunch, multilingual sites, MCP, EU AI Act and Cyber Resilience Act.
Download the free TYPO3 guides