Custom Content Elements in TYPO3 with Mask (Guide for 2026)

Note: If you add the dependency after TYPO3 Mask has already been installed and activated, you must rebuild the loading order by reinstalling your extension.

Required Static TypoScript and fluid_styled_content

Mask requires fluid_styled_content. Make sure it is included in your static TypoScript bindings in the TYPO3 template module.

In Composer mode, you can install it with:

bash

composer require typo3/cms-fluid-styled-content

After installing Mask:

1. Open the Template module in the TYPO3 backend.
2. Select your site’s template.
3. Add the static TypoScript from TYPO3 Mask to your template.
4. Ensure that fluid_styled_content is included in the static bindings.

This step ensures that Mask’s configuration and content rendering work correctly.

Preparing Your Sitepackage for Mask

Before using TYPO3 Mask, set up a sitepackage (your own TYPO3 extension for templates and configuration). This is where Mask stores its generated configuration, templates, and overrides, keeping your project clean and maintainable.

Your sitepackage should have:

• An extension key (e.g. site_vendor or site_project).
• A basic folder structure for Configuration, Resources, and TCA overrides.
• A registered TypoScript template for your site.

Versioning LocalConfiguration.php and Mask Config for Teams

Mask stores configuration in LocalConfiguration.php and in JSON files inside your sitepackage. For teams and multiple environments (local, staging, production), keep these under version control.

• Add Mask config files (JSON/YAML/TS) to your sitepackage and commit them to Git.
• Avoid relying only on LocalConfiguration.php; document Mask-related settings if you use it.
• Use a workflow:
  • Create/update Mask elements in one environment (local dev).
  • Export changes into the sitepackage (config + templates).
  • Commit and deploy to other environments.

• This keeps your Mask setup consistent and makes onboarding easier.

Step-by-Step: Create Your First Custom Content Element with Mask

Open the Mask Backend Module

• Find the Mask module in the TYPO3 backend (below Extension Manager).
• Open it and enter your sitepackage extension key if prompted.
• Ensure your sitepackage is loaded.

Define the Element (Name and Key)

1. Click “Create new content element”.
2. Enter:
   1. Name: e.g. “Teaser Box”, “Hero Banner”.
   2. Key: unique, lower-case (e.g. teaser_box, hero_banner).
3. Click “Finish”. The Mask builder opens with the “Fields” tab selected.

Add Fields via Drag and Drop

• Go to the “Fields” tab.
• Drag or click a field type to add it.
• Configure the field on the right (label, description, type).
• Field keys start with tx_mask_ (e.g. tx_mask_title, tx_mask_teaser_image).

Common options:

• Field key: column name in tt_content.
• Label: what editors see.
• Description: helper text.
• Reset to default: resets TCA options.

Example “Teaser Box” fields:

• tx_mask_title (Text)
• tx_mask_teaser_text (text area)
• tx_mask_image (image)

Save and Check the Generated TCA

When you save:

• Mask generates TCA for your fields in tt_content
• TCA defines database columns, backend display, and validation.

You don’t write TCA manually, but knowing Mask generates it helps when debugging.

Place the Element on a Page and Test the Frontend

1. Go to the Page module.
2. Click “Create new content element” and find your element by name.
3. Add it, fill in fields, and save.
4. Click “View webpage” to test the frontend.

If it doesn’t render:

• Check the Fluid template path.
• Confirm Mask’s TypoScript and fluid_styled_contentare included.
• Clear TYPO3 and PHP caches.

Working with TCA and Advanced Field Options in Mask

Creating custom content elements in TYPO3 isn’t just about defining fields visually; TYPO3 needs TCA (Table Configuration Array) to know how to store and display them. Mask automatically generates this TCA for you, while still giving you control over key field options. This section explains what TCA is, how Mask uses it, and which field options you can configure.

What Is TCA and Why It Matters for Mask?

The Table Configuration Array (TCA) is a core concept in TYPO3 development. It defines the structure and behavior of database tables used by TYPO3 to store content items, including custom content items created with TYPO3 Mask. For Mask, TCA tells TYPO3 how to display and handle your custom fields in the backend and frontend.

How Mask Uses TCA for Your Content Elements

When you create custom content elements with Mask, TCA is automatically generated and used in several key ways:

• Database structure
  TCA defines the structure of tt_content table where your content items are stored. For custom fields in Mask, TCA defines how data is stored (column names, types, and relationships).
• Field configuration
  TCA lets you configure field properties:
  • Field type (text, number, image, select, etc.)
  • Label and description
  • Validation rules and default values
  • This ensures data consistency and integrity.
• Integration with TYPO3 Core
  TCA integrates your Mask-generated elements with TYPO3 core features like translations, versioning, and access control.
• Customization and extensibility
  TCA offers extensive customization options, allowing you to adjust element behavior and appearance without writing TCA manually.

In short, Mask generates all necessary TCA for you, while you control key field options through the backend UI.

Common Field Options and Reset to Default

Most fields in Mask share these common options:

• Field key
  Unique key for the field. It determines the new column name in tt_content and must be unique and lower-case.
• Label
  What editors see when editing the content item. It can be localized for translations.
• Description
  Optional helper text below the label to guide editors.
• Reset to default
  Resets all TCA options for the field back to defaults, except label and description. Use this to quickly undo changes without recreating the field.

These options make it easy to configure fields for editors while keeping the underlying TCA consistent and maintainable.

Using the “Element Metadata” Tab for Better Editor Experience

The Element Metadata tab is not just for technical details; it’s where you make your content elements clear and easy for editors. By filling in metadata, you improve how your elements appear in the creation wizard and backend, helping editors choose and use the right element correctly.

What You Can Configure in Element Metadata

• Short title
  A concise title shown when editors select the element type. If left blank, the default title is used.
• Description
  A short explanation of what the element is for. It appears next to the title and preview image in the creation wizard and helps editors understand the element’s purpose.
• Icon
  Choose a preview icon from FontAwesome. You can select from different categories or search by keyword. If no icon is set, Mask generates a fallback symbol using the first letter of your label.
• Color
  Adjust the icon color to improve visual distinction between different element types.

Spending a few minutes filling in these fields makes your content elements much more editor-friendly, especially in larger projects with many elements.

Page Templates and Mask (Optional but Powerful)

Mask can extend page records and backend layouts (page templates), letting you add fields to pages, not just content areas.

• Define fields on the pages table.
• Fields appear in page properties based on backend layout.
• Use for site-wide or page-level settings.

Common use cases:

• Global hero image or banner
• Page-level toggles (“Show news”, “Hide sidebar”)
• Page-specific SEO overrides
• Page-type selectors (“landing page”, “blog post”)

Great for agencies needing consistent page structures across client sites.

Structuring Mask for Agencies and Larger Projects

Organize Mask for reuse across multiple client sites:

• Store Mask config (JSON/YAML) and templates in your sitepackage.
• Use clear folder structure: Resources/Private/Templates/Content/.
• Export Mask config to JSON and commit to Git for sharing across environments.
• Use prefixes:
  • CTypes: site_feature_hero, site_feature_teaser
  • Fields: tx_mask_hero_title, tx_mask_teaser_text
• Group by feature (hero, teaser, faq, form).

Common Problems and Troubleshooting with TYPO3 Mask

Element not visible:

• Check CType in Mask.
• Clear caches.
• Include Mask’s TypoScript.
• Load your sitepackage.

Fields not shown:

• Verify field keys are correct/unique.
• Flush caches, reload Mask config.
• Check TCA overrides.
• Load sitepackage before Mask.

Template not rendering:

• Confirm Fluid template path.
• Match template name to config.
• Clear caches and opcache.
• Include Mask’s TypoScript.

Composer/dependency issues:

• Reinstall extension if dependency added later.
• Check composer.json.
• Ensure Mask loads before sitepackage.

Clear caches, check load order, and verify config to fix most issues.

Alternatives to Mask and When to Use Core Methods

Even though Mask simplifies custom content elements, TYPO3 also offers a core method to create them without extra extensions.

Manual TYPO3 Core Method

With the core method, you create custom content elements by:

• Defining a new CType and adding it to the New Content Element Wizard via Page TSconfig.
• Adding TCA in Configuration/TCA/Overrides/tt_content.php.
• Registering TypoScript and static templates in your sitepackage.
• Creating Fluid templates, partials, and layouts for rendering.

This gives you full control using only TYPO3 core, but you must write and maintain all configuration manually.

Official docs:

• Create a custom content element type (latest): t3coreapi:adding-your-own-content-elements
• TYPO3 11.5 / 12.4 pages on “Create a custom content element type”.

When Mask Is Overkill

Mask might be more than you need if:

• You have a very small site with only one or two simple elements.
• Your team is comfortable with TCA, TypoScript, and Fluid and prefers code.
• You want a minimal, extension-free stack (policy reasons).
• You’re building a one-off feature unlikely to be reused or maintained by non-developers.

In these cases, the core method or simple content blocks may be enough.

When Mask Is a Clear Win

Mask shines for agencies and teams when:

• You build many TYPO3 projects and want reusable patterns.
• You have non-PHP integrators or editors who shouldn’t touch TCA/TypoScript/PHP.
• You want a visual builder with drag-and-drop, JSON config, and auto-generated code.
• You need to iterate quickly on content structures without refactoring boilerplate.

Use the core method when you want maximum control with minimal dependencies; use Mask when you want speed, safety, and editor-friendly workflows at scale.

Summary and Next Steps

Using TYPO3 Mask for custom content elements lets you skip most of the low-level TCA and TypoScript work while still building clean, flexible structures. It speeds up development, improves the editor experience with better labels, icons, and metadata, and reduces boilerplate compared to the manual core method.

If you want to go further with Mask and TYPO3, good next topics include:

• Multi-language content elements with Mask
  How to configure fields, labels, and templates so your custom elements work cleanly across multiple languages.
• Mask + AI content workflows in TYPO3
  How to combine Mask-based elements with AI-assisted content generation and editing (e.g. structured content fields that feed AI tools).

Conclusion

TYPO3 Mask revolutionizes content creation in TYPO3 by providing a user-friendly way to create custom content elements without writing all TCA and TypoScript by hand. With its intuitive interface, flexible configuration options, and seamless integration into the TYPO3 core, Mask helps developers and agencies build dynamic, editor-friendly websites efficiently.

If you want expert support planning or implementing Mask in larger TYPO3 projects, you can get in touch with NITSAN as your TYPO3 agency partner for guidance, best practices, and long-term maintenance strategies.