When I needed a comments system for a MODX website, it quickly became clear that I did not just want a form with a “Your comment” field.
I wanted a complete, practical component that could be installed once and then reused across different projects without constant workarounds.
And the list of requirements turned out to be quite specific.
- I wanted comments to work without page reloads, through AJAX, while keeping the actual MODX page fully cacheable.
- I wanted proper threaded discussions, where users could reply not only to the first comment but also to other replies, without breaking the thread structure during pagination or deletion.
- I wanted both guest comments and authenticated users, while MODX administrators should not need to log in separately on the frontend if they were already authenticated in the manager.
- I wanted authors to be able to edit and delete their own comments for a configurable period of time, and I wanted guest ownership to be handled securely as well.
- I wanted proper moderation: immediate publishing or pending approval, statuses such as pending, spam and published, and separate rules for guests and authenticated users.
- I wanted a proper comments management panel inside MODX, with search, filters, publishing, moderation, spam marking, soft deletion and permanent deletion from the database.
- I wanted 👍 / 👎 voting, pagination, permanent comment links, relative timestamps, convenient replies, quoting, emoji and link insertion.
- I wanted email notifications for administrators and reply authors, while keeping email templates editable through normal MODX Chunks.
- I wanted anti-spam protection without being locked to one CAPTCHA provider, so the component should support Cloudflare Turnstile, hCaptcha, Google reCAPTCHA v2/v3 and Yandex SmartCaptcha.
- I also wanted the whole system to be properly secured: CSRF protection, resource signing, rate limiting, safe guest cookies, server-side CAPTCHA verification, escaped user content and no way to use the public connector as an arbitrary write endpoint.
And there was one more important requirement: I did not want to maintain two separate components for MODX 2 and MODX 3.
I wanted one transport package that could be installed on an old MODX 2.8 project as well as on MODX 3.
And ideally, installation should come down to something as simple as this:
[[ModxComments]]
Install the package, add one snippet call — and the comments work.
That is how ModxComments was created: a free comments component for MODX Revolution that works with both MODX 2.8.x and MODX 3.0–3.2.
Project repository:
https://github.com/web86/ModxComments
The component is free, and the source code is openly available in the repository.
Why the comments are AJAX-based
One of the main ideas behind ModxComments is that comments should not interfere with page caching.
A regular MODX page can remain fully cached:
[[ModxComments]]
The page HTML is rendered by MODX as usual, while the comments list is loaded separately through AJAX.
The same approach is used for:
-
posting comments;
-
replying to comments;
-
voting;
-
editing;
-
deleting;
-
switching comment pages.
So there is no need to make the whole resource uncached or turn the page into a collection of [[!Snippet]] calls.
One package for MODX 2 and MODX 3
This is one of the main features of ModxComments.
The same transport package can be installed on:
-
MODX Revolution 2.8.x;
-
MODX Revolution 3.0;
-
MODX Revolution 3.1;
-
MODX Revolution 3.2.
Internally, the component contains separate compatibility layers for MODX 2 and MODX 3, and the correct implementation is selected automatically.
So a site owner does not need to wonder:
“Is this the MODX 2 version or the MODX 3 version?”
There is only one package.
Threaded comments
Comments support full reply trees.
Users can reply to a root comment or to an existing reply.
The result looks like a normal discussion tree:
Comment
└── Reply
└── Reply to a reply
└── Another reply
The maximum nesting depth is configurable in MODX system settings.
For example:
modxcomments.max_depth = 5
The internal structure is stored in a way that keeps the thread intact during pagination.
Guest comments and authenticated users
The component supports both authenticated MODX users and regular site visitors.
Guests can submit comments with their name and email address.
For authenticated users, author data is taken from their MODX profile.
Guest comments can also be disabled completely through a system setting.
Administrators can comment too
There is another small but useful feature.
If an administrator is already logged into the MODX manager, the component can recognize that session on the frontend.
There is no need to log in again as a separate web user.
Administrator comments receive a special badge:
★ Admin Administrator Name
The displayed name comes from the MODX user profile.
Editing and deleting your own comments
After submitting a comment, its author can edit or delete it for a configurable amount of time.
The time window is controlled by:
modxcomments.edit_time = 900
900 seconds means 15 minutes.
For authenticated users, ownership is determined by their MODX user ID.
For guests, a separate secure browser identifier is used. The raw secret token is never stored in the database — only its hash is stored.
Soft deletion
When a user deletes their own comment, the database record is not physically removed.
This is important for discussion trees.
Imagine the following structure:
Comment #1
└── Reply #2
└── Reply #3
If comment #1 were simply removed from the database, its replies would lose their parent.
So regular deletion is soft deletion: the comment content is hidden, while the thread structure remains intact.
Permanent deletion from the manager
Administrators have a separate action:
Delete permanently
This really removes the comment from the database.
If the selected comment has replies, those replies are removed as well.
Related votes are also deleted.
So after permanent deletion, the database no longer contains the selected comment, its descendant thread or any associated vote records.
The regular soft-delete action remains available for normal moderation.
Comment moderation
New comments can either:
-
be published immediately;
-
be sent for moderation.
The rules can be configured separately for guests and authenticated users.
For example:
modxcomments.guest_status = pending
modxcomments.user_status = published
With this setup, comments from authenticated users are published immediately, while guest comments require moderator approval.
Comments management panel
After installation, MODX gets a separate menu item:
Comments
From there, administrators can:
-
view all comments;
-
search by text, name and email;
-
filter comments;
-
inspect threads and replies;
-
publish comments;
-
send comments back to moderation;
-
mark comments as spam;
-
soft-delete comments;
-
permanently delete comments.
Replies also show which comment they were posted under.
Administrator-authored comments are highlighted separately.
Voting 👍 / 👎
Each published comment can have a rating.
Users can vote with:
-
👍
-
👎
A vote can also be changed or removed.
For authenticated users, the vote is linked to the user account.
For guests, a secure browser identifier is used.
Anti-spam protection
The component includes several anti-spam layers.
Rate limiting
You can configure how many comments can be submitted within a certain period of time.
For example:
modxcomments.rate_limit_count = 5
modxcomments.rate_limit_window = 60
This allows no more than five comments per minute.
The IP address is not stored in plain text — only a hash is stored.
Honeypot
The form contains a hidden honeypot field for simple bots.
Normal users never see it, while many automated spambots fill it in.
Multiple CAPTCHA providers
CAPTCHA is not tied to a single service.
The following providers are currently supported:
-
Cloudflare Turnstile;
-
hCaptcha;
-
Google reCAPTCHA v2;
-
Google reCAPTCHA v3;
-
Yandex SmartCaptcha;
-
or CAPTCHA can be disabled entirely.
The provider is selected through:
modxcomments.captcha_provider
For example:
turnstile
or:
hcaptcha
or:
recaptcha
or:
yandex
CAPTCHA can also be required only for guests:
modxcomments.captcha_guests_only = 1
Authenticated users can then comment without CAPTCHA.
Server-side CAPTCHA verification
CAPTCHA is not validated only in JavaScript.
The token is always sent to the server, and the component verifies it through the selected CAPTCHA provider API.
That means simply sending a POST request directly to the endpoint is not enough to bypass the check.
For Google reCAPTCHA v3, the score is also validated.
The minimum score can be configured:
modxcomments.recaptcha_min_score = 0.5
Email notifications
ModxComments can send notifications about new comments.
Administrator notifications can be enabled with:
modxcomments.notify_admin = 1
The recipient email address can be configured separately. If it is left empty, the standard MODX emailsender setting is used.
The component can also notify a comment author when a new published reply is posted to their comment.
Editable email templates
Email content is stored in regular MODX Chunks.
For example:
ModxCommentsEmailAdminSubject
ModxCommentsEmailAdminBody
ModxCommentsEmailReplySubject
ModxCommentsEmailReplyBody
They can be edited directly in the MODX manager.
User-edited templates are preserved during component upgrades.
Pagination
Large discussions do not have to load hundreds of threads at once.
The number of root discussion threads per page is controlled by:
modxcomments.threads_per_page = 20
Replies belonging to each visible root thread are loaded together with it.
This means a reply tree is never split between pages.
Frontend conveniences
The frontend includes a number of small details that make the comment system more pleasant to use:
-
threaded replies;
-
parent comment quote previews;
-
editing without reloading the page;
-
deletion without browser
alert()orprompt()dialogs; -
character counter;
-
link insertion;
-
emoji;
-
relative timestamps such as “5 minutes ago”;
-
permanent comment links such as
#comment-123; -
automatic scrolling to a newly submitted comment;
-
highlighting of a newly added comment;
-
loading and submission states;
-
a visible “awaiting moderation” state.
Russian and English interfaces
The frontend and manager interfaces use separate MODX lexicons.
Out of the box, the component includes:
-
Russian;
-
English.
Interface text is not hard-coded directly in JavaScript.
Additional translations can be added through the normal MODX lexicon mechanism.
Security
A lot of attention was paid to making sure the public AJAX API could not be used as an arbitrary write endpoint.
Every rendered comments widget receives a signed resource token.
The token is tied to:
-
the resource ID;
-
the MODX context;
-
a private site secret.
The signing key is generated automatically during installation:
modxcomments.resource_signing_key
This prevents someone from simply taking the public comments API and passing an arbitrary resource ID to it.
The component also includes:
-
CSRF protection;
-
permission checks;
-
server-side CAPTCHA verification;
-
request size limits;
-
HttpOnly cookies;
-
SameSite cookies;
-
safe handling of user content;
-
URL validation;
-
protection against MODX tag execution inside email templates;
-
manager session validation;
-
POST-only administrative mutations.
Unexpected public errors do not expose internal PHP exceptions or server file paths.
User content remains safe
Comments are not treated as HTML.
User-provided HTML is never executed.
Text is escaped, while safe HTTP/HTTPS links are supported.
Users can write:
https://example.com
or:
[Link title](https://example.com)
Everything else remains plain text.
MODX events
The component provides its own MODX events for integration with other functionality:
ModxCommentsBeforeCommentCreate
ModxCommentsOnCommentCreate
ModxCommentsOnCommentUpdate
ModxCommentsOnCommentDelete
ModxCommentsOnCommentPublish
ModxCommentsOnCommentVote
This makes it possible to attach a custom MODX plugin and extend the behavior.
For example:
-
send a Telegram notification;
-
synchronize comments with an external system;
-
run an additional anti-spam check;
-
collect custom statistics.
How to install ModxComments
Installation is standard for MODX.
Download the transport ZIP and install it through:
Packages → Installer
Then clear the MODX cache.
Ready-to-install builds and source code are available in the repository:
https://github.com/web86/ModxComments
A separate directory is provided for ready-made transport packages:
distr/
How to display comments
After installation, add this snippet call to the desired resource or template:
[[ModxComments]]
That is all.
You do not need to manually include the connector, JavaScript or CSS.
The component loads the required frontend files automatically.
The snippet call itself can remain cacheable.
Basic configuration
For most sites, only a few settings are needed.
For example:
modxcomments.allow_guests = 1
modxcomments.guest_status = pending
modxcomments.user_status = published
modxcomments.max_depth = 5
modxcomments.threads_per_page = 20
If CAPTCHA is needed:
modxcomments.captcha_enabled = 1
modxcomments.captcha_provider = turnstile
modxcomments.captcha_guests_only = 1
Then simply configure the keys for the selected CAPTCHA provider.
Who is this component for?
ModxComments can be useful for:
-
blogs;
-
articles;
-
news sites;
-
documentation;
-
catalogs;
-
product pages;
-
service pages;
-
small communities;
-
any MODX site that needs discussions.
The component does not dictate the structure of your template and barely interferes with the page rendering itself.
Free to use
ModxComments is a free component.
The project started from a practical need: I wanted a modern comments system that could be used both on older MODX 2 projects and on MODX 3 without maintaining two separate codebases.
If the component turns out to be useful for other projects as well, then the goal has been achieved.
Source code, documentation and the latest version are available here:
https://github.com/web86/ModxComments
To use it, install the package and add:
[[ModxComments]]
That is all. The component takes care of the rest.

