The Custom HTML module is the single most useful tool in Joomla's core toolbox. It is a box you can fill with any markup you like — a banner, a notice, an embed code, an opening-hours table — and publish anywhere your template has a position. Half the "which extension should I install for X" questions we get can be answered with "none, use a Custom HTML module", and the site ends up leaner for it.
Yet the module has a reputation for being fiddly, and the reputation is deserved in exactly one respect: the WYSIWYG editor. Paste carefully crafted HTML into the default editor, hit save, and watch it strip your iframe, rewrite your attributes and swallow your markup whole. Every frustration we have ever seen with this module traces back to that filtering pipeline, and it is completely avoidable once you know where the switches are.
This tutorial walks through the whole process on Joomla 3, 4 and 5: creating the module, getting HTML past the editor intact, assigning positions and pages, scheduling, embedding modules inside articles, and keeping your snippets maintainable as the site grows.
Step 1: Create the module
The path differs slightly by version, but the destination is the same screen:
- Joomla 4 / 5: log in to the administrator, go to Content, then Site Modules, and click the New button.
- Joomla 3: go to Extensions, then Modules, and click New.
- From the list of module types, choose Custom (labelled Custom HTML in Joomla 3).
- Give the module a descriptive title. You will thank yourself in a year when the module list has forty entries — "Banner — summer promo, homepage" beats "Custom HTML (3)".
- Decide whether visitors should see that title: the Show Title option next to the position field toggles it. For banners and embeds you usually want it hidden.
At this point you have an empty module and a content area with an editor in it. Before you type anything, deal with the editor.
Step 2: Stop the editor from eating your HTML
Joomla's default editor, TinyMCE, is a word processor. It exists to protect content editors from broken markup, so it removes tags it considers dangerous or invalid — iframes, scripts, sometimes divs with unfamiliar attributes, and occasionally things it just does not like that day. For writing a paragraph of text this is fine. For pasting an embed code it is fatal.
You have three ways around it, in increasing order of permanence:
Toggle the code view (quick and risky)
TinyMCE has a source-code view. Paste your HTML there and save without switching back to the visual view. This works for simple markup but still passes your HTML through the editor's cleanup on save, so complex snippets can get mangled anyway.
Switch your editor to None or CodeMirror (recommended)
Joomla lets every admin user pick their own editor, so you can keep TinyMCE for content writers while you use a raw editor:
- Click your user name in the top-right of the admin, then Edit Account (or go to Users, Manage, and open your account).
- On the Basic Settings tab, set Editor to None (a plain textarea) or CodeMirror (a code editor with syntax highlighting).
- Save, then reopen your Custom HTML module. The content area is now a raw HTML field that saves exactly what you type.
CodeMirror is the nicer daily driver — highlighting catches unclosed tags before they bite. This per-user switch is the single best Joomla habit we can recommend to anyone who touches markup.
Adjust text filters (site-wide, handle with care)
Even with the editor out of the way, Joomla's global Text Filters (in Global Configuration) can strip tags on save depending on your user group. If iframes vanish even in CodeMirror, check that your group is set to No Filtering or has the specific tags allowed. Loosen filters only for trusted admin groups — those filters are a security layer for lower-privilege users, and the official Joomla documentation explains the trade-offs well.
Step 3: Add your HTML
With a raw editor active, paste or write your markup. A simple notice block might look like:
<div class="site-notice">
<h3>Holiday opening hours</h3>
<p>We are closed from 24 December to 2 January.
Orders placed in that window ship on 3 January.</p>
<a href="/contact/">Questions? Contact us</a>
</div>Style it from your template's custom CSS file rather than inline attributes — the markup stays clean, and restyling later means editing one stylesheet instead of every module. Give your modules' wrapper divs consistent class names and they can share styles; the module class suffix on the Advanced tab offers another styling hook, which we put to work in our guide to creating call-to-action blocks in Joomla.
Step 4: Assign a position
A module renders only when it sits in a position your template outputs on the page. The Position dropdown on the module edit screen lists every position from every installed template, which is more confusing than helpful — make sure you pick one belonging to your active site template. Selecting a position from a template you are not using is a classic reason a module "does not work".
If you do not know which position corresponds to which spot on the page, there is a built-in preview: enable Preview Module Positions in the template settings and append ?tp=1 to your site URL. Our walkthrough on how to find template module positions in Joomla covers it screenshot by screenshot, and if the perfect spot simply does not exist in your template, it takes about ten minutes to add a new module position yourself.
One non-obvious trick: the position field accepts free text. Type a position name that does not exist in any template — say inline-promo — and press enter. The module will never render in a template position, but it becomes available to the loadposition tag inside articles, which is exactly what you want for in-content blocks (Step 7).
Step 5: Choose which pages show it
The Menu Assignment tab controls page visibility, and it works by menu item:
- On all pages — the default, right for site-wide notices.
- Only on the pages selected — tick specific menu items.
- On all pages except those selected — the inverse.
- No pages — hidden everywhere (still available to loadposition on some setups, but do not rely on it).
The catch: assignment follows menu items, not URLs. A page reached without any menu item — some component views, search results — inherits assignment from the default menu item, which can make modules appear or vanish in surprising places. When a module shows where it should not, menu assignment is the first thing to audit.
Step 6: Publish, schedule, order
Three more fields on the module screen do quiet but important work:
| Setting | What it does | Watch out for |
|---|---|---|
| Status | Published, Unpublished or Trashed | Unpublished modules still clutter the list — trash what is truly dead |
| Start Publishing | Module appears automatically at a date and time | Server timezone vs your timezone — check Global Configuration |
| Finish Publishing | Module disappears automatically | The silent killer: modules that "mysteriously vanished" months later |
| Ordering | Sequence when several modules share one position | Drag to reorder in the module list, filtered by position |
The scheduling fields are genuinely useful — build a holiday banner in November, set its start and finish dates, and forget about it. Just remember the finish date exists when a module disappears and you are sure you never touched it.
Step 7: Embed the module inside an article
Template positions cover headers, sidebars and footers, but sometimes the block belongs in the middle of an article. Joomla's core Content - Load Modules plugin (check it is enabled under System, Plugins) provides two tags you can type into any article:
{loadposition inline-promo}— renders every module assigned to the position inline-promo at that spot in the text.{loadmoduleid 42}— renders one specific module by ID (Joomla 4 and later; earlier versions use a loadmodule tag with type and title).
Combined with the free-text position trick from Step 4, loadposition gives you swappable in-content slots: articles reference the position name, and you decide in the module manager what renders there this month. If the tag shows up as literal text on the site, the plugin is disabled or the editor converted your characters into something else — retype it in code view.
What people actually use this module for
A quick tour of real-world uses we have shipped, to spark ideas:
- Announcement bars — holiday hours, shipping deadlines, maintenance notices.
- Calls to action — headline, sentence, button, published after content or mid-article.
- Third-party embeds — map iframes (see our Google Maps Joomla module guide), booking widgets, video players, newsletter forms.
- Trust blocks — certifications, association logos, payment icons in the footer.
- Opening hours and contact snippets — a small table in the sidebar, reused across the site.
- Structured one-offs — anything a page needs once that does not justify an extension.
The pattern in all of these: content that is not an article, laid out in markup you control, published precisely where it belongs.
Keeping your snippets maintainable
Custom HTML modules accumulate. A five-year-old Joomla site can easily have sixty of them, half unpublished, several containing phone numbers that changed twice. A little discipline prevents the mess:
- Name with a convention. Prefix by purpose: "CTA — quote — sidebar", "Embed — map — contact", "Notice — holidays". The module list becomes searchable.
- One fact, one module. If your opening hours appear in three modules, they will eventually disagree. Keep one module and publish it in multiple positions, or reference one position from several articles via loadposition.
- Style centrally. Classes in the module, rules in the template's custom CSS. No inline styling to hunt through later.
- Keep an off-site copy of complex snippets. The editor-filter pipeline means a bad save can destroy markup; a folder of .html files in your project notes is cheap insurance.
- Audit yearly. Filter the module list by Unpublished and trash the dead wood. Check Finish Publishing dates on anything seasonal.
FAQ
Why does my HTML change or disappear after saving the module?
Two filters stand between your markup and the database: the WYSIWYG editor's cleanup and Joomla's global Text Filters. TinyMCE strips or rewrites tags it distrusts — iframes are its favourite victim — and Text Filters can remove more on save depending on your user group. Switch your editor to None or CodeMirror in your user profile, and if things still vanish, review Text Filter settings for your group in Global Configuration.
Can I put JavaScript in a Custom HTML module?
Technically yes, if your editor and text filters allow script tags for your user group — that generally means an admin account with filtering set to none. Whether you should is another matter: scripts pasted into modules are invisible to anyone auditing the template and easy to forget. For a third-party widget snippet it is acceptable; for anything substantial, a template override or a small extension keeps the site more maintainable. Never loosen script filtering for user groups you do not fully trust.
What is the difference between loadposition and loadmodule?
The loadposition tag renders all modules assigned to a named position, respecting each module's menu assignment and publishing state — good for reusable slots whose content you manage from the module list. The loadmodule and loadmoduleid tags target one specific module regardless of position — good for embedding exactly one thing exactly once. For in-article CTAs and promos we default to loadposition, because it lets you swap content later without editing articles.
My module is published but does not show on the site. What do I check?
Work down this list: the position belongs to your active template (not another installed one); Menu Assignment includes the page you are viewing; Status is Published and no Finish Publishing date has passed; the module is not restricted by Access level to a group your test visitor lacks; and finally the template actually outputs that position on this page layout — some templates collapse positions on certain views. Nine problems out of ten live in the first two items.
The bottom line
The Custom HTML module is Joomla's utility knife: banners, notices, embeds, CTAs and one-off blocks, all without installing anything. The entire skill boils down to three habits — edit with CodeMirror or None so your markup survives saving, pick positions and menu assignments deliberately, and name and style your modules like someone else will inherit them. Master those and you will reach for this module weekly. For the rest of our Joomla series, from menus to favicons, head over to the Joomla hub.