11 Methods to add CSS/JS Frontend Assets into TYPO3

Q: What is the best way to add CSS and JavaScript in modern TYPO3?

For TYPO3 v10 and above, Fluid Asset ViewHelpers and AssetCollector are the recommended approaches. They provide better control, predictable rendering, and are upgrade-safe.

Q: Should I still use includeJS or includeCSS in TYPO3?

includeJS and includeCSS are still supported, but they are considered legacy methods. They should mainly be used when maintaining older TYPO3 projects.

Q: What is AssetCollector used for in TYPO3?

AssetCollector is used to register and manage CSS and JavaScript centrally, especially in Extbase extensions. It helps avoid duplication and improves render order control.

Q: Can I mix multiple methods to add CSS/JS in TYPO3?

It’s technically possible, but not recommended. Mixing TypoScript, Fluid, and PHP-based asset inclusion can lead to unpredictable behavior and debugging issues.

Q: Should JavaScript be loaded in the header or footer in TYPO3?

Whenever possible, JavaScript should be loaded in the footer to reduce render-blocking and improve performance. TYPO3 provides multiple ways to control this.

Q: Which method should I use when upgrading an older TYPO3 project?

For upgrades, keep existing methods stable first, then gradually migrate to AssetCollector or Fluid Asset ViewHelpers to align with modern TYPO3 best practices.

Published on : 26 Oct 2021

Markus Neumann

Maintenance

Looking to enhance your TYPO3 website's functionality and aesthetics? Discover 11 ways to add CSS/JS frontend assets with this comprehensive guide.

11 Methods to add CSS/JS Frontend Assets into TYPO3

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.

That flexibility is intentional. It allows TYPO3 projects to stay stable, maintainable, and future-ready.

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

How to add CSS/JS assets into TYPO3?

Which Method Should You Use to Add CSS/JS in TYPO3?

TYPO3 offers multiple ways to include CSS and JavaScript, but not every method fits every use case. The right approach depends on your role, your TYPO3 version, and whether you’re working on a template, page, or extension.

Use the guidance below to quickly identify the most suitable method before diving into the full list.

If you are a TYPO3 Integrator (Template / Site Setup)

Use Fluid Asset ViewHelpers (<f:asset.css />, <f:asset.script />) - Best for template-based asset inclusion in modern TYPO3 versions
Use AssetCollector (via Extbase or PHP) - Recommended when assets must be managed programmatically
Avoid relying on legacy TypoScript methods unless required by an older project

Goal: clean structure, predictable rendering, future-safe upgrades

If you are a TYPO3 Extension Developer

Use Extbase AssetCollector - Official, modern way to register CSS/JS from extensions
Use inline assets only when dynamic output is unavoidable
Avoid additionalHeaderData / additionalFooterData in new extensions

Goal: encapsulated assets, upgrade-safe extensions, no global side effects

If you are Maintaining or Extending an Older TYPO3 Project

Existing TypoScript methods (includeJS, includeCSS, HeaderData) may still be valid
Prefer gradual migration to AssetCollector when upgrading TYPO3
Avoid mixing multiple asset injection methods on the same page

Goal: stability first, modernization step by step

Quick Rule of Thumb

TYPO3 v10+ → Prefer AssetCollector and Fluid Asset ViewHelpers
TYPO3 v8–v9 → TypoScript and Fluid sections may still be common
Extensions → Always think AssetCollector first

The sections below explain all 11 methods in detail, including when and how each one is used.

Modern vs Legacy Ways to Add Assets in TYPO3

TYPO3 provides multiple ways to include CSS and JavaScript, but not all approaches carry the same weight today. Some methods are modern and recommended, while others exist primarily for backward compatibility.

The classification below helps you understand which approaches TYPO3 encourages today and which ones should be used only when maintaining older projects.

Modern & Recommended Approaches

These methods align with current TYPO3 architecture and are suitable for new projects and ongoing development:

Fluid Asset ViewHelpers (<f:asset.css />, <f:asset.script />)
Designed for modern TYPO3 templates with clear asset handling and predictable rendering.
Extbase AssetCollector
The recommended approach for extensions and dynamic asset registration, offering better control, priority handling, and upgrade safety.

Legacy or Backward-Compatible Approaches

These methods are still supported but are generally intended for older TYPO3 projects or specific edge cases:

TypoScript-based asset inclusion (includeJS, includeCSS, HeaderData, FooterData)
Inline JavaScript or CSS via TypoScript
additionalHeaderData / additionalFooterData in Extbase controllers

Why This Distinction Matters

Modern methods improve maintainability, performance control, and upgrade safety
Legacy methods increase the risk of unpredictable render order and technical debt
Mixing modern and legacy approaches on the same page often leads to hard-to-debug issues

The detailed sections below explain all 11 methods, including when legacy approaches may still be necessary.

TYPO3 Fluid ViewHelper (>= v10.3)

From TYPO3 v10 onwards, Fluid Asset ViewHelpers provide a clean and structured way to include CSS and JavaScript in TYPO3 templates.

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/Css/myCustom.js" />
<f:asset.script identifier="yourIdentifier">
  alert('hello world');
</f:asset.script>

Reference: View Document

TYPO3 Fluid Assets (>= v8.6)

Since TYPO3 v8, Fluid HeaderAssets and FooterAssets allow you to define frontend assets directly inside Fluid templates using dedicated sections.

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

While still supported, this approach is more commonly found in older TYPO3 setups and is often replaced by AssetCollector or Fluid Asset ViewHelpers in newer projects.

<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

HeaderData TypoScript (>= v4)

HeaderData 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.

This method is primarily used in legacy TYPO3 projects and should be avoided in new implementations unless backward compatibility is required.

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

FooterData TypoScript (>= v4)

FooterData works similarly to HeaderData, 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 TypoScript (>= v4)

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.

Although still supported, this method is considered legacy in modern TYPO3 projects and should be used cautiously alongside newer asset-handling mechanisms.

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

Tips:
You can use config.moveJsFromHeaderToFooter to shift scripts for better performance.

jsInline TypoScript (>= v4)

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 {
   // Your JavaScript code
}

includeCSS TypoScript (>= v4)

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 TypoScript (>= v4)

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;}
}

Extbase additionalFooterData (>= v6)

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.

It is generally considered legacy for new extension development.

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

Extbase additionalHeaderData (>= v6)

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

While still functional, it is not recommended for modern TYPO3 extensions.

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

Extbase AssetCollector (>= v10.3)

From TYPO3 v10 onwards, AssetCollector is the recommended way to manage CSS and JavaScript in Extbase extensions.

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/Css/myCustom.js',

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

  );

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::getInlineStyleSheetsAssetCollector::getMedia()

Reference: View Document

Recommended Methods by TYPO3 Version

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 v13 / v12

Recommended

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

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 maintenance.

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

Rendering Order of Assets in TYPO3

Last but not least, with the above so many ways - You may have questions about the exact render order or priority of assets in TYPO3.

From v10.3, 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()

Performance Considerations When Adding CSS and JavaScript in TYPO3

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.

Performance Best Practices (Quick Checklist)

Load JavaScript in the footer whenever possible
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 upgrade-friendly.

Common Mistakes When Adding CSS and JavaScript in TYPO3

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

Wrapping up!

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, and choose the asset strategy that fits your setup.

FAQs

For TYPO3 v10 and above, Fluid Asset ViewHelpers and AssetCollector are the recommended approaches. They provide better control, predictable rendering, and are upgrade-safe.

includeJS and includeCSS are still supported, but they are considered legacy methods. They should mainly be used when maintaining older TYPO3 projects.

AssetCollector is used to register and manage CSS and JavaScript centrally, especially in Extbase extensions. It helps avoid duplication and improves render order control.

It’s technically possible, but not recommended. Mixing TypoScript, Fluid, and PHP-based asset inclusion can lead to unpredictable behavior and debugging issues.

Whenever possible, JavaScript should be loaded in the footer to reduce render-blocking and improve performance. TYPO3 provides multiple ways to control this.

For upgrades, keep existing methods stable first, then gradually migrate to AssetCollector or Fluid Asset ViewHelpers to align with modern TYPO3 best practices.

Do you need help maintaining and supporting (SLA) your TYPO3 website?

2 Days of quick support (reaction and resolution time)
3 Packages plans available for TYPO3 SLA (service level agreement)
3 Timezone support available (CET, CEST, IST)
2 Languages support available (English, German)
1 Monthly updates & report (TYPO3 security & maintenance)

TYPO3 SLA Gig

Markus Neumann

Template Support Manager

Markus lives and breathes TYPO3 templates. Known for his structured thinking and eye for detail, he’s helped hundreds of customers build faster, cleaner TYPO3 sites. If there’s a template issue, Markus has probably solved it…

11 Methods to add CSS/JS Frontend Assets into TYPO3

If you are a TYPO3 Integrator (Template / Site Setup)

If you are a TYPO3 Extension Developer

If you are Maintaining or Extending an Older TYPO3 Project

Quick Rule of Thumb

Modern & Recommended Approaches

Legacy or Backward-Compatible Approaches

Why This Distinction Matters

TYPO3 v13 / v12

TYPO3 v11 / v10

TYPO3 v9 / v8

TYPO3 v7 and Earlier

Important Reminder

Header vs Footer Loading

Render-Blocking Risks

Why AssetCollector Helps Performance

Performance Best Practices (Quick Checklist)

1. Using Legacy TypoScript Methods in Modern TYPO3 Versions

2. Mixing Multiple Asset Injection Methods on the Same Page

3. Relying Too Heavily on Inline JavaScript or CSS

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

5. Ignoring Render Order and Dependencies

6. Skipping Cleanup During TYPO3 Upgrades

FAQs

Do you need help maintaining and supporting (SLA) your TYPO3 website?

Markus Neumann

TYPO3 + WordPress: Case Study of TYPO3 Slider Revolution

T3Planet – Introducing Ideal Subscription Model

Post a Comment

You May Also Like

Why Your Business Needs SLAs: Benefits and Advantages Explained

TYPO3 Gitlab CI/CD Auto Deployment (2024)

TYPO3 Composer vs TER - What's Better TYPO3 Installation Method?