Joomla Custom HTML Modules — Building Custom Content and Layouts

In this tutorial, you'll learn how to build custom layouts in Joomla using Custom HTML modules — writing raw HTML and CSS, applying module class suffixes for styling, using content preparation plugins, and creating reusable layout components for banners, social links, footers, and call-to-action blocks.

What You'll Learn

• What Custom HTML modules are and when to use them
• Creating a Custom HTML module with raw HTML content
• Using content preparation plugins: email cloaking, load module, load position
• Applying module class suffixes for custom CSS styling
• Module chrome options for wrapping and styling
• Creating fixed and sticky modules with CSS
• Module layout overrides using template overrides
• Responsive module classes for mobile/tablet/desktop
• Common use cases: copyright footer, social icons, contact info, newsletter signup

Why It Matters

Not everything on a website comes from the article manager. Banners, social media icons, newsletter signup forms, copyright notices, and promotional call-to-action boxes are all examples of content that belongs in modules, not articles. Custom HTML modules give you a blank canvas to create exactly what you need without installing additional extensions. They are the most versatile tool in Joomla's module system.

Real-World Use

A law firm website needs a copyright notice in the footer, social media icons in the header, a "Schedule a Consultation" call-to-action box in the sidebar, and a banner advertising a free guide in the content area. Instead of installing four different extensions, the developer creates four Custom HTML modules, writes the HTML directly, styles them with module class suffixes, and assigns each to the appropriate position using menu assignment.

Learning Path

flowchart LR
  A["Modules & Positions"] --> B["Custom HTML Modules
You are here"]:::current
  B --> C["Next: Template Basics"]

  classDef current fill:#38bdf8,color:#0f172a,stroke-width:2px

What Are Custom HTML Modules?

A Custom HTML module is a blank canvas where you can write any HTML, CSS, and JavaScript. It displays the content you enter, wrapped in the module chrome provided by your template.

Unlike articles, Custom HTML modules:

• Do not have categories or tags
• Do not have version history
• Do not appear in category listings
• Are not indexed by Smart Search by default
• Are not affected by article-level permissions
• Cannot have comments or ratings (without extensions)

Use Custom HTML modules when you need:

• A block of static content (copyright, contact info)
• Custom HTML that does not fit Joomla's article structure
• Third-party embed codes (Google Maps, newsletter forms, social widgets)
• Decorative or promotional content in sidebars and footers

Creating a Custom HTML Module

1. Go to Extensions > Modules.
2. Click the New button.
3. Select Custom HTML from the module type list.
4. Enter a Title (e.g., "Footer Copyright").
5. In the Content editor, write your HTML.
6. Configure module options (position, assignment, permissions).
7. Save.

Writing HTML Content

The content editor works the same as the article editor. You can use TinyMCE to write visually or switch to Code Mirror for raw HTML editing.

Example: Simple copyright footer:

<p class="copyright">
    &copy; 2026 My Company. All rights reserved.
    Built with <a href="https://www.joomla.org">Joomla</a>.
</p>

Example: Social media icons:

<div class="social-links">
    <a href="https://facebook.com/mycompany" class="social-icon facebook"
       target="_blank" rel="noopener">
        Facebook
    </a>
    <a href="https://twitter.com/mycompany" class="social-icon twitter"
       target="_blank" rel="noopener">
        Twitter
    </a>
    <a href="https://linkedin.com/company/mycompany" class="social-icon linkedin"
       target="_blank" rel="noopener">
        LinkedIn
    </a>
</div>

Example: Call-to-action box:

<div class="cta-box">
    <h3>Get Started Today</h3>
    <p>Sign up for a free consultation and see how we can help your business grow.</p>
    <a href="/contact" class="cta-button">Schedule a Call</a>
</div>

Preparing Content

When you save a Custom HTML module, Joomla runs content plugins on the HTML. This enables several useful features.

Email Cloaking

If you include an email address in the module, the Email Cloaking plugin automatically converts it to a protected format that spam bots cannot read.

<p>Contact us at <a href="mailto:info@example.com">info@example.com</a></p>

The plugin cloaks this on output.

Load Module Plugin

The Load Module plugin lets you embed another module inside your Custom HTML module. This is useful for nesting modules.

{loadmodule mod_latestnews,Latest News}

Parameters: module type, module title (or module ID).

Load Position Plugin

The Load Position plugin renders all modules in a position inside your Custom HTML module.

{loadposition position-7}

This renders the entire sidebar inside your custom module.

Content Preparation Sequence

When a Custom HTML module is rendered:

1. Joomla retrieves the raw HTML from the database.
2. Content plugins Process the HTML (email cloaking, load module, load position, page break).
3. The module chrome wraps the processed content.
4. The result is inserted into the template position.

Module Class Suffix for Custom HTML Modules

Module class suffixes are especially useful with Custom HTML modules because they let you style the wrapper.

How It Works

The module class suffix is added to the module's container div. Your template generates HTML like this:

<div class="moduletable my-suffix">
    <h3>Module Title</h3>
    <div class="module-content">
        ... your HTML ...
    </div>
</div>

Example Suffixes

Styling with CSS

Add CSS to your template's user.css file:

.cta-banner {
    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
    color: white;
    padding: 25px;
    border-radius: 10px;
    text-align: center;
}

.cta-banner a {
    display: inline-block;
    background: white;
    color: #667eea;
    padding: 10px 25px;
    border-radius: 5px;
    text-decoration: none;
    font-weight: bold;
    margin-top: 10px;
}

.footer-copyright {
    font-size: 14px;
    color: #666;
    text-align: center;
    padding: 10px 0;
}

.social-icons {
    display: flex;
    gap: 15px;
    justify-content: center;
}

.social-icons a {
    color: #333;
    text-decoration: none;
    font-size: 20px;
}

Module Chrome Options

The chrome option controls how the module is wrapped by the template.

No Wrapper (Out)

Select "Out" from the Style dropdown. The module content is output without any surrounding divs or heading tags. Use this when you want complete control over the HTML structure.

Standard (HTML)

The default chrome. Adds the standard module wrapper div and heading.

Custom Chrome Types

Depending on your template, you may have additional chrome types:

• Table: Wraps in a table layout
• Horizontal: Horizontal layout for menu items
• Rounded: Adds rounded corners
• Outline: Adds a border outline

Fixed and Sticky Modules

You can make a module stick to the viewport as the user scrolls using CSS.

.mod-sticky {
    position: sticky;
    top: 20px;
}

Apply the class suffix "mod-sticky" to your module. The module stays visible as users scroll past it. Works well for sidebar modules like contact forms or call-to-action boxes.

Module Layout Overrides

You can override the default module layout without modifying the core extension files.

Creating an Override

1. Go to Extensions > Templates > Templates.
2. Click on your active template (e.g., Cassiopeia).
3. Click the Create Overrides tab.
4. Find mod_custom in the list and click to create the override.
5. The override file is created at templates/your-template/html/mod_custom/default.php.

Editing the Override

Open the override file:

<?php
// mod_custom override
defined('_JEXEC') or die;
?>

<div class="custom-module">
    <?php echo $module->content; ?>
</div>

This replaces the default chrome with your custom wrapper.

Responsive Module Classes

Use CSS to control module visibility on different screen sizes.

Hide on Mobile

.hide-mobile {
    display: block;
}

@media (max-width: 768px) {
    .hide-mobile {
        display: none;
    }
}

Hide on Desktop

.hide-desktop {
    display: none;
}

@media (max-width: 768px) {
    .hide-desktop {
        display: block;
    }
}

Responsive Column Classes

If your template uses Bootstrap, use column classes:

<div class="row">
    <div class="col-md-6">
        <!-- Left content -->
    </div>
    <div class="col-md-6">
        <!-- Right content -->
    </div>
</div>

Common Uses for Custom HTML Modules

1. Copyright Footer

<p class="copyright-text">
    &copy; 2026 Company Name. All rights reserved.
    Powered by <a href="https://www.joomla.org">Joomla</a>.
    Built by the developers of <a href="#">Doda Browser</a>,
    <a href="#">DodaZIP</a>, and <a href="#">Durga Antivirus Pro</a>.
</p>

Module class suffix: footer-copyright Position: position-9 (footer)

2. Social Media Icons

<div class="social-links">
    <a href="https://facebook.com/company" class="fab fa-facebook"
       target="_blank" rel="noopener noreferrer"
       aria-label="Follow us on Facebook"></a>
    <a href="https://twitter.com/company" class="fab fa-twitter"
       target="_blank" rel="noopener noreferrer"
       aria-label="Follow us on Twitter"></a>
    <a href="https://linkedin.com/company/company" class="fab fa-linkedin"
       target="_blank" rel="noopener noreferrer"
       aria-label="Follow us on LinkedIn"></a>
</div>

Module class suffix: social-icons Position: position-1 (header) or position-7 (sidebar)

3. Contact Info

<div class="contact-info-module">
    <div class="contact-item">
        <span class="icon">&#9742;</span>
        <span>+1 (555) 123-4567</span>
    </div>
    <div class="contact-item">
        <span class="icon">&#9993;</span>
        <span>info@example.com</span>
    </div>
    <div class="contact-item">
        <span class="icon">&#9906;</span>
        <span>123 Main Street, City, State 12345</span>
    </div>
</div>

Module class suffix: contact-info Position: position-7 (sidebar)

4. Newsletter Signup

<div class="newsletter-box">
    <h3>Stay Updated</h3>
    <p>Get the latest news and offers delivered to your inbox.</p>
    <form action="https://example.com/subscribe" method="post">
        <input type="email" name="email" placeholder="Your email address"
               required class="newsletter-input">
        <button type="submit" class="newsletter-button">Subscribe</button>
    </form>
</div>

Module class suffix: newsletter-box Position: position-7 (sidebar) or position-12 (above main)

Security Note

Custom HTML modules execute the HTML, CSS, and JavaScript you enter. This means:

• Users with permission to edit Custom HTML modules can inject JavaScript
• Only trust Super Users and Administrators with this permission
• Validate any third-party embed codes before adding them
• JavaScript from Custom HTML modules runs in the context of your site

If your site has multiple content authors, consider whether they need Custom HTML module access or if articles suffice.

Common Mistakes

1. Forgetting to add module class suffix: Write your HTML, style it, but forget to add the suffix. The module appears unstyled because the CSS class is missing from the wrapper.

2. Using the article editor for module content: TinyMCE can add unwanted formatting to HTML. Use Code Mirror for raw HTML editing in Custom HTML modules to maintain control.

3. Not testing responsive behavior: A Custom HTML module that looks perfect on desktop may overflow or break on mobile. Always test on multiple screen sizes.

4. Overusing Custom HTML modules: If you need the same custom content on multiple pages, consider creating a module layout override or a custom module type instead of copy-pasting the HTML.

5. Ignoring email cloaking: If you put email addresses in Custom HTML modules, ensure the Content - Email Cloaking plugin is enabled to protect them from spam harvesters.

Practice Questions

1. What is the difference between a Custom HTML module and an article in Joomla? Answer: A Custom HTML module is a raw HTML block displayed in a module position, without categories, tags, version history, or article features. An article is structured content with full CMS features like categories, tags, featured status, and version history.

2. How can you make a Custom HTML module sticky so it stays visible while scrolling? Answer: Add a module class suffix like "mod-sticky" and add CSS: .mod-sticky { position: sticky; top: 20px; }. This makes the module stick to the viewport as the user scrolls.

3. What is the Load Module plugin and how is it used in Custom HTML modules? Answer: The Load Module plugin lets you embed one module inside another using syntax like {loadmodule mod_latestnews,Latest News}. It renders the specified module's output inside your Custom HTML content.

4. Challenge: Build a complete footer for a website using only Custom HTML modules. The footer should have: a copyright notice, three column sections (About, Services, Contact), social media links, and a newsletter signup form. Use module class suffixes for styling, ensure responsive behavior, and use the appropriate chrome option for each module.

FAQ

Mini Project

Your task: Build a promotional call-to-action section for a website using Custom HTML modules.

1. Create a Custom HTML module with a call-to-action box containing:
   • A heading: "Ready to Get Started?"
   • A description paragraph explaining the offer
   • A button linking to a contact page
   • A background color or gradient (inline CSS)
2. Add a module class suffix "promo-cta" and style it with CSS in user.css.
3. Create a second Custom HTML module with social media icons using Font Awesome or SVG icons.
4. Create a third Custom HTML module with a newsletter signup form (HTML only, no backend processing).
5. Assign each module to appropriate positions: promo in position-12 (above main), social in position-1 (header), newsletter in position-7 (sidebar).
6. Test the responsive behavior and adjust CSS for mobile screens.

What's Next

This completes the content management and navigation modules. Your next area of study is templates and design:

Continue to the next module to learn about Joomla templates. Start with Template Basics to understand Cassiopeia, template manager, and template styles.

Related lessons:

• Joomla Modules and Module Positions — Understanding module positions is essential for Custom HTML modules
• Joomla Content Modules — Other content display modules complement Custom HTML