How To Create Custom Element In TYPO3 [Ultimate Guide]
A TYPO3 custom content element helps developers create reusable content blocks that match a project’s exact design, structure, and editor needs.
![How To Create Custom Element In TYPO3 [Ultimate Guide]](/fileadmin/ns_theme_ns2019/blog/_live/TYPO3_Content_Element/Wie_man_benutzerdefinierte_Elemente_in_TYPO3_erstellt.jpg)
Instead of relying only on default TYPO3 content elements, teams can build custom elements for sections such as CTA boxes, card grids, sliders, code blocks, product highlights, or structured landing page components.
To create a custom content element in TYPO3, define a new CType, configure the required TCA fields, add the element to the New Content Element Wizard, set up frontend rendering with TypoScript and a Fluid Template, and optionally add a backend preview or DataProcessor for better editor experience.
What Is a Custom Content Element in TYPO3?
A TYPO3 custom content element is a reusable content block built for a specific website need. It can include custom fields, backend settings, and a Fluid Template for frontend output.
Editors see it in the TYPO3 backend under Create New Content Element once it is added to the content element wizard.
Type | Meaning |
Content Element | A reusable page block used to display structured content, such as CTA sections, cards, testimonials, banners, or information blocks. |
Plugin | A dynamic functionality component used for advanced features such as search, filters, forms, user interactions, or data-driven listings. |
Template | Defines the frontend presentation and layout structure, controlling how content elements and plugins appear on the website. |
Extension | A complete TYPO3 package that can contain custom content elements, plugins, templates, configuration files, database structures, and backend/frontend logic. |
Custom content elements help keep content structured, reusable, and easier for editors to manage.
How Do You Create a TYPO3 Custom Content Element?
To create a TYPO3 custom content element, register a new CType, configure the required TCA fields, add the element to the New Content Element Wizard, and define the frontend output with TypoScript and a Fluid Template.
You can also add a backend preview for editors and use a DataProcessor when the element needs extra data handling before rendering.
TYPO3 Custom Elements vs Core Elements
TYPO3 core elements are built-in content elements that cover common needs like text, images, media, tables, and standard layouts. A TYPO3 custom content element is created when a project needs a specific layout, field structure, or frontend output that core elements cannot provide.
Factor | TYPO3 Core Element | TYPO3 Custom Element |
Purpose | Used for standard website content requirements provided by TYPO3 by default. | Created for project-specific content requirements and unique website components. |
Editor Control | Provides basic editing options with predefined fields and settings. | Offers custom fields, flexible configurations, and tailored editor controls. |
Frontend Output | Uses predefined layouts and rendering structures. | Provides complete control over frontend design, structure, and rendering. |
Best Use | Suitable for common content types such as text, images, and media elements. | Ideal for advanced components such as CTA sections, cards, sliders, product blocks, and custom business modules. |
Custom elements are useful when editors need repeatable, structured content blocks instead of building the same layout manually on every page.
When Should You Create a Custom TYPO3 Content Element?
Create a custom TYPO3 content element when the website needs a reusable section with a fixed design, clear fields, and controlled frontend output.
A custom content element is useful when:
- You need reusable branded sections
- Editors need structured fields
- The design needs strict frontend control
- You want fewer unnecessary dependencies
- You need better content consistency across pages
- You want a custom backend preview for editors
Do not create a custom content element when:
- A TYPO3 core element already solves the need
- A simple Fluid Template override is enough
- A plugin is better for dynamic logic, listings, forms, filters, or complex workflows
Core CType, Content Blocks, or Extension: Which Method Should You Use?
TYPO3 offers different ways to create custom content elements. The right method depends on how much control, flexibility, and logic the project needs.
Method | Best For | Pros | Watch Out |
Core CType Method | Projects requiring full developer control over custom content elements. | Stable, flexible, and fully aligned with TYPO3 Core architecture. | Requires more manual configuration and development effort. |
Content Blocks | Building structured content elements quickly with a modern workflow. | Simplifies configuration, reduces development time, and provides a cleaner element-building approach. | Requires the Content Blocks Extension and proper setup. |
Plugin / Extbase Extension | Features requiring dynamic business logic and complex functionality. | Best suited for forms, data-driven listings, workflows, and advanced interactions. | Requires more development expertise and has a more complex setup. |
Third-party Tools | Quick implementation for simple website requirements. | Faster setup with ready-made solutions and less custom development. | Creates dependency risks and may affect long-term maintenance or TYPO3 upgrades. |
Use the Core CType method when the project needs full control over fields, rendering, backend preview, and long-term maintainability.
Use Content Blocks when you want a faster way to build structured content elements with less manual configuration.
Use a Plugin or Extbase Extension when the feature needs dynamic logic, records, filters, forms, search, or custom workflows.
Prerequisites Before Creating a TYPO3 Custom Element
Before creating a TYPO3 custom content element, make sure the project has the right setup.
You should have:
- A TYPO3 v12, v13, or v14 project
- A sitepackage or custom Extension
- Composer-based TYPO3 setup
fluid_styled_contentinstalled and configured- Access to TCA, PageTSconfig, TypoScript, and Fluid Templates
- Basic PHP and Fluid knowledge
- A local or staging environment for safe testing
Do not create or test custom content elements directly on a live website. Use a local or staging setup first, then deploy after testing the backend, frontend, cache behavior, and editor workflow.
File Structure for a TYPO3 Custom Content Element
A clear TYPO3 custom element file structure makes the setup easier to build, test, and maintain. Most custom content elements use files for CType registration, TCA fields, wizard setup, frontend rendering, and optional backend preview logic.
File / Folder | Purpose |
| Register CType and fields |
| Add database fields |
| Add wizard configuration |
| Define frontend rendering |
| Add the Fluid Template |
| Add an optional DataProcessor |
| Add backend preview or rendering logic |
This structure keeps the custom element organized and makes it easier to update later.
What Fields and Factors Are Included in a TYPO3 Content Type?
A TYPO3 content type usually includes the settings needed to show the element in the backend, store its fields, and render it on the frontend.
Key parts include:
- CType key for identifying the custom element
- Database fields for storing custom values
- TCA configuration for backend field setup
- Wizard entry for adding the element in the backend
- Backend preview for editor visibility
- TypoScript rendering for frontend output
- Fluid Template for the element layout
- Optional DataProcessor for extra data handling
- Language labels for backend field names
- Icon identifier for the content element icon
These parts work together to make the custom content element usable for editors and render correctly on the website.
Step-by-Step: Create a Custom TYPO3 Content Element with Core CType
This method gives developers full control over the content element setup, including backend fields, editor preview, frontend rendering, and data processing. It follows the classic TYPO3 Core CType approach using TCA, PageTSconfig, TypoScript, and Fluid Template rendering.
1. Define the CType Key
Start by defining a clear and unique CType key for the custom content element. This key identifies the element inside TYPO3.
Use a short, readable, and project-specific key.
Example:
myextension_newcontentelement
Best practice:
- Use lowercase letters
- Avoid spaces and special characters
- Prefix the key with your Extension name
- Keep the key meaningful and easy to recognize
2. Register the Icon
Register an icon for the custom content element so editors can recognize it in the TYPO3 backend.
// typo3conf/ext/myextension/ext_localconf.php
$iconRegistry = \TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance(
\TYPO3\CMS\Core\Imaging\IconRegistry::class
);
$iconRegistry->registerIcon(
'my-icon-identifier',
\TYPO3\CMS\Core\Imaging\IconProvider\FontawesomeIconProvider::class,
['name' => 'external-link-square']
);
The icon identifier should match the identifier used in the content element registration.
3. Add the Element to the Type Dropdown
Next, add the custom content element to the TYPO3 CType dropdown. This makes the element available as a selectable content type in the backend.
// typo3conf/ext/myextension/Configuration/TCA/Overrides/tt_content.php
\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addTcaSelectItem(
'tt_content',
'CType',
[
'LLL:EXT:myextension/Resources/Private/Language/Tca.xlf:myextension_newcontentelement',
'myextension_newcontentelement',
'my-icon-identifier',
],
'header',
'after'
);
This step only registers the element as a content type. The fields, rendering, and wizard entry still need to be configured separately.
4. Add Database Fields
If the custom content element needs its own field, add it to ext_tables.sql.
Example:
CREATE TABLE tt_content (
code_language text DEFAULT '' NOT NULL
);
Use custom database fields only when the default tt_content fields are not enough.
5. Configure TCA Fields
TCA controls how fields appear and behave in the TYPO3 backend.
Example:
$additionalColumns = [
'code_language' => [
'label' => 'LLL:EXT:codeblock/Resources/Private/Language/locallang_db.xlf:tt_content.code_language',
'config' => [
'type' => 'select',
'default' => '',
'itemsProcFunc' => 'NITSAN\\Codeblock\\DataProvider\\CodeLanguages->getAll',
'renderType' => 'selectSingle',
],
],
];
\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addTCAcolumns(
'tt_content',
$additionalColumns
);
\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addToAllTCAtypes(
'tt_content',
'code_language',
'codeblock',
'before:bodytext'
);
For TYPO3 v13.3 and newer, avoid repeating unnecessary system fields for tt_content content types. TYPO3 already handles several standard fields automatically.
6. Add the Element to the New Content Element Wizard
To let editors select the element from the New Content Element Wizard, add PageTSconfig.
mod.wizards.newContentElement {
wizardItems {
common.elements.codeblock {
title = LLL:EXT:codeblock/Resources/Private/Language/locallang_db.xlf:tt_content.CType
description = LLL:EXT:codeblock/Resources/Private/Language/locallang_db.xlf:tt_content.wizard.description
tt_content_defValues.CType = codeblock
iconIdentifier = content-codeblock
}
common.show := addToList(codeblock)
}
}
This makes the custom content element easier for editors to find and use.
7. Add Backend Preview
A backend preview is optional, but it helps editors understand what the custom content element contains without opening it.
There are two common ways to add a preview:
Fluid Preview
Use a Fluid preview Template through PageTSconfig:
mod.web_layout.tt_content.preview.codeblock = EXT:codeblock/Resources/Private/Templates/Preview/Codeblock.html
This is useful for simple previews based on saved field values.
Custom Preview Renderer
For more control, use a custom preview renderer.
$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['cms/layout/class.tx_cms_layout.php']['tt_content_drawItem']['content-codeblock']
= \Vendor\YourExtensionKey\Hooks\PageLayoutView\NewContentElementPreviewRenderer::class;
Use a custom renderer when the preview needs special logic, formatted output, or custom backend display.
8. Add a DataProcessor
A DataProcessor is useful when the content element needs extra data handling before rendering.
Use it for:
- Files
- Related records
- External data
- Array transformation
- Syntax highlighting
- Custom field processing
Example:
public function process(
ContentObjectRenderer $cObj,
array $contentObjectConfiguration,
array $processorConfiguration,
array $processedData
) {
$fieldName = $processorConfiguration['field'];
$targetVariableName = $cObj->stdWrapValue('as', $processorConfiguration, 'bodytext_formatted');
$highlight = GeneralUtility::makeInstance(Highlighter::class);
if (!$processedData['data']['code_language']) {
$languages = $highlight->listLanguages();
$highlight->setAutodetectLanguages($languages);
$highlighted = $highlight->highlightAuto($processedData['data'][$fieldName]);
} else {
$highlighted = $highlight->highlight(
$processedData['data']['code_language'],
$processedData['data'][$fieldName]
);
}
$processedData[$targetVariableName]['code'] = $highlighted->value;
$processedData[$targetVariableName]['language'] = $highlighted->language;
return $processedData;
}
A DataProcessor keeps logic outside the Fluid Template and makes the rendering cleaner.
9. Add TypoScript Configuration
TYPO3 needs TypoScript configuration to render the custom content element on the frontend.
tt_content.codeblock =< lib.contentElement
tt_content.codeblock {
templateName = Codeblock
templateRootPaths.0 = EXT:codeblock/Resources/Private/Templates
dataProcessing.1567071612 = NITSAN\Codeblock\DataProcessing\HighlightProcessor
dataProcessing.1567071612 {
field = bodytext
as = bodytext_formatted
}
}
This connects the custom CType with its Fluid Template and optional DataProcessor.
10. Add the Fluid Template
Create the Fluid Template that controls the frontend output.
Example:
<f:layout name="Default" />
<f:section name="Main">
<pre>
<code class="hljs {bodytext_formatted.language}">
{bodytext_formatted.code -> f:format.raw()}
</code>
</pre>
</f:section>
Use raw output only when the content is trusted or properly sanitized. For normal editor input, escape output by default to avoid security issues.
Modern Option: Create Custom Elements with TYPO3 Content Blocks
Quick answer: Content Blocks are a simplified way to define structured content elements in TYPO3.
Instead of setting up every part manually with TCA, PageTSconfig, TypoScript, and backend configuration, Content Blocks let developers define content elements in a more compact structure. A typical Content Block includes a config.yaml file, a Fluid Template, optional assets, and language labels.
Content Blocks are useful when you need faster setup for structured elements such as hero sections, CTA blocks, card layouts, sliders, teasers, or reusable landing page sections. They are especially helpful in TYPO3 v13 and v14 projects where teams want a cleaner and more modern workflow for custom content elements.
Use the Core CType method when the project needs full control, complex TCA setup, custom processing, or long-term low-level flexibility. Use Content Blocks when the goal is to create structured content elements faster with less manual configuration.
TYPO3 v14 Notes: Visual Editor and Editor Experience
TYPO3 v14 brings stronger focus to editor experience. The Visual Editor supports plain text and rich text editing, content reordering with drag and drop, highlighted editable fields, and permission-aware editing through TYPO3 APIs.
This matters for custom content elements because Templates should not only render correctly on the frontend. They should also be easy for editors to understand and manage.
When creating custom elements for TYPO3 v14, check:
- Plain text fields are easy to edit
- Rich text fields render safely and correctly
- Editable fields are clear in the editing workflow
- Content elements can be reordered without breaking layout
- Templates are structured for editor-friendly output
- Backend permissions and field access work as expected
A good custom content element should help editors update content without guessing how the layout works.
SEO, Accessibility, and Performance Best Practices
Custom TYPO3 content elements should be built for users, editors, search engines, and long-term maintenance.
SEO Best Practices
- Keep a clear semantic heading order
- Avoid duplicate H1 tags inside custom elements
- Use clean and descriptive link labels
- Keep important text visible in the HTML
- Support structured content instead of layout-only content
- Avoid hiding key content behind JavaScript-only output
Accessibility Best Practices
- Use semantic HTML elements
- Add alt text fields when images are used
- Use accessible buttons and links
- Keep keyboard navigation working
- Avoid visual-only content without text alternatives
- Check contrast, focus states, and readable spacing
Performance Best Practices
- Load CSS and JavaScript only when the element is used
- Avoid unnecessary frontend assets
- Use optimized images
- Use TYPO3 caching correctly
- Keep DataProcessor logic lightweight
- Avoid heavy external calls during rendering
A custom content element should not only look correct. It should load fast, stay accessible, support SEO, and remain easy to maintain during future TYPO3 updates.
Common Mistakes When Creating TYPO3 Custom Elements
Custom TYPO3 content elements often fail because small setup steps are missed. These are the most common mistakes to avoid:
- CType is not registered correctly
- Element does not appear in the backend wizard
- TCA override file is placed in the wrong path
- TYPO3 cache is not flushed after changes
- TypoScript setup is not included
- Fluid Template path is incorrect
- Database field is added in code but not applied in the database
- Frontend output does not render
- Backend preview is missing or broken
- Language labels are missing
- Raw output is used without proper escaping or sanitizing
These issues are usually easy to fix when the file structure, CType key, TCA setup, TypoScript configuration, and Template paths are checked step by step.
Troubleshooting: Custom Element Not Showing or Rendering
Problem | Likely Cause | Fix |
Element Not in Wizard | PageTSconfig configuration is missing or incorrect. | Add the required wizard configuration and clear/flush the TYPO3 cache. |
Field Not Visible | TCA configuration is not loaded properly. | Check the TCA override file and verify the CType configuration. |
Frontend Blank | TypoScript setup is missing or the CType configuration is incorrect. | Include |
Template Not Found | Incorrect Fluid template path or template name. | Check |
Database Error | Required database field has not been added. | Run the database compare tool or execute the required migration. |
Preview Not Shown | Backend preview hook or configuration issue. | Check the backend preview renderer configuration or Fluid preview setup. |
Labels Missing | Language file is missing or translation keys are incorrect. | Verify XLF label file paths and check translation keys. |
Output Unsafe | Raw HTML output is used without proper handling. | Escape output by default and sanitize only trusted HTML content. |
Custom Element Example: CTA Box
A CTA box is a practical TYPO3 custom content element because it is useful for agencies, marketing teams, and editors. It gives editors a fixed structure instead of asking them to build the same section manually on every page.
A simple CTA box can include:
- Header
- Body text
- Button text
- Button link
- Image
- Background style
This type of custom content element works well for landing pages, service pages, campaign pages, and blog CTAs. Developers can control the frontend output with a Fluid Template, while editors only manage the fields they need.
Custom Element Checklist Before Go-Live
Before publishing a TYPO3 custom content element, check the full workflow from backend editing to frontend output.
- CType works in the TYPO3 backend
- Element appears in the New Content Element Wizard
- Fields save correctly
- Frontend renders correctly
- Fluid Template path is correct
- Backend preview is clear for editors
- Language labels are added
- Output is escaped or sanitized
- Accessibility is tested
- Mobile layout is tested
- Cache behavior is checked
- Editor workflow is tested
- TYPO3 v13/v14 compatibility is checked
A custom content element is ready for go-live only when developers and editors can both use it without errors.
Conclusion
Creating a custom content element in TYPO3 gives developers better control over structure, fields, frontend output, and editor experience.
Use the Core CType method when the project needs full control over TCA, TypoScript, Fluid Templates, backend preview, and custom processing. Use Content Blocks when you need faster structured content elements with a simpler setup. Use plugins or Extensions when the feature needs dynamic logic, records, forms, filters, listings, or workflows.
The best TYPO3 custom content element is not only technically correct. It should be easy for editors to use, safe for future upgrades, optimized for performance, accessible for users, and structured properly for SEO.
A Structured Start for TYPO3 Projects
Use this guide to avoid common mistakes and lay a solid foundation for your TYPO3 project from the beginning.
FAQs
A TYPO3 custom content element is a reusable content block created for a specific website need. It can include custom fields, backend settings, frontend rendering, and a Fluid Template.
Create it by registering a CType, configuring TCA fields, adding it to the New Content Element Wizard, defining TypoScript rendering, and creating a Fluid Template.
CType is the content type identifier in TYPO3. It tells TYPO3 which content element is being used and which backend fields, rendering setup, and Template should apply.
Use Content Blocks for faster structured elements with simpler configuration. Use Core CType when you need full control, advanced TCA setup, custom rendering, or complex project-specific behavior.
A custom Extension or sitepackage is recommended because it keeps the configuration, Templates, TypoScript, labels, and backend setup organized.
Add it using PageTSconfig. This makes the custom content element visible under Create New Content Element in the TYPO3 backend.
Contact for Internet agency and TYPO3 projects
Sven Thelemann
Service Partner - Germany
Sven Thelemann
Client Service LeadSven Thelemann serves as the Client Service Lead at NITSAN, focusing on delivering TYPO3 solutions that meet client goals. With a strong understanding of technology and client expectations, he ensures smooth communication and project execution. Outside of work, Sven enjoys cycling and experimenting with homemade recipes.
Be the First to Comment