Look and Feel
Pagination & Sorting
The Reply Box
Customizations and Configuration
Here you will find in-depth documentation on each of the features and settings that the comment widget supports.
This documentation will cover core concepts, and will go deep into each area of functionality, with how-tos and common gotchas.
Code examples will be provided, with relevant lines highlighted. Screenshots of configuration pages will be provided where applicable.
Most configuration and features outlined in this guide do not require writing any code.
Since the urlId parameter allows us to define which page, or id, the comments are tied to, we can simply set urlId to the same value on those pages.
FastComments is designed to be customized, and the font our widgets use is no exception.
By default, FastComments uses the
system font stack to look as good as possible on a wide range of devices.
To define your own fonts, see the Custom CSS documentation.
There you will find a way to define custom CSS, which will allow you to define your desired fonts.
How to Define The Font
To override the font, we recommend you define your CSS using the
.fast-comments, textarea selectors. For example:
By default, the FastComments comment widget will automatically detect dark mode on most sites.
When dark mode is detected, FastComments will switch from black text on white backgrounds to white text on a black background. Images will also change.
On page load, the widget will try to determine how dark the background of the page is behind the comment widget. This means that the page could have a white background, but if you put the comment widget inside a container with a black background, dark mode should still automatically be enabled to make the comments readable.
However, the detection mechanism, which relies on determining "luminance", may not enable dark-mode when you want to. To forcefully enable it, set the hasDarkBackground flag to true as follows:
When sending notification emails, or rendering comments in user interfaces like the moderation page, it's helpful to be able to link from the comment to the page it's on.
If URL ID isn't always an ID, then we have to store the URL some place else. That's what the "url" property is for, defined as follows.
A common use case is tying the comment thread to an identifier, like an article, and then linking back to a particular page, for example:
The URL does not get cleaned of common marketing parameters. By default, whatever the current page URL is, is the URL stored with the comment.
When fetching and rendering comments, the comment widget needs to know which page to start on. By default, it starts with the first page, only rendering that page.
If desired, the exact page to be rendered can be passed to the comment widget as the setting startingPage.
Note that pages numbers start from zero, so the above example renders the second page.
We've covered how
urlId is the page or article id the comments are tied to.
Also, to recap, if not defined the
urlId will default to the current page URL.
What about SPAs, or Single-Page-Applications, where the page or content the comments are tied to changes dynamically without a fresh page reload?
Angular, React, Vue, etc
With our libraries such as Angular and React, simply updating the
urlId property passed to the widget
will cause the comment widget to refresh. You can see this in action for the React app, for example, here.
If you're using the VanillaJS library it is slightly more complicated as there isn't a framework like Angular or React to handle the data binding or state propagation.
When you instantiate the VanillaJS widget, it returns some functions which can be called to update it.
Here's a functional example where we change the page hash and update the comment widget:
By default, FastComments allows users to upload images. When a user clicks that image, FastComments will, by default, open a new tab to show that image in full. Setting this flag to true disables this behavior:
If you don't plan to capture the image click yourself (see onImageClicked), we recommend this is combined with some styling to remove the appearance that the image can be clicked.
By default, FastComments will show a success message after commenting. This can be disabled as follows:
This can currently not be done without code.
By default, the FastComments widget will resize itself vertically to fit all visible comments. Pagination is achieved via a "View Next" button at the end of the current page, as we have found this to be the interaction that feels the nicest for most users.
However, there are some cases where infinite scrolling is preferred. For example, we use this feature in our Stream Chat product.
We can hide the "View Next" buttons and switch to infinite scrolling by setting the enableInfiniteScrolling flag to true:
This also requires the addition of custom CSS to be added. Add custom CSS for the
.comments selector to enable scrolling, for example:
A full working example would be:
In the above example we use the
customCSS property, however it is suggested the Widget Configuration UI is used instead for performance reasons. See the Custom CSS documentation.
To disable pagination, and just render all comments at once, set startingPage to -1.
SSO, or single-sign-on, is a set of conventions used to allow you or your users use FastComments without having to create another account.
Assuming you don't allow anonymous commenting, an account is required to comment with FastComments. We make this sign up process very easy - the user just leaves their email when they comment. However, we understand that even that is extra friction some sites want to avoid.
We can reduce that friction by only having one login flow for your entire site.
How do I get it?
All account types currently get access to SSO. However, the max number of SSO users will vary depending on your package. As with other features, the Pro plans and higher provide direct development support.
Let's compare the options, and then go into details of each.
User and Comment Migrations
When migrating from a platform with SSO like Disqus, you will already have users and their comments.
Comments are imported as part of your migration, either by the API, our Import UI, or customer support. The Import UI is preferred if it supports the platform you are migrating from, as it incorporates error handling, avatar and media extraction and uploads, and a batch job monitoring system.
The users themselves are added automatically when viewing comment threads for the first time. Alternatively, they can be pre-added via the API, but this work does not have many advantages.
If comments are imported, and SSO users are not added manually via the API, then comments will automatically be migrated to the user's account the first time it is created when they view any comment thread. They will then be able to manage, edit, and delete the comments they originally wrote.
The automatic migration is done via email or username. Some platforms do not provide emails on export, like Disqus, so we fall back to username in this case.
- As long as you pass a matching username, and an email in the SSO payload, we will add the email to the individual comment objects so that notifications and mentions work.
If it is desired to import your comments and users at once, work with support to migrate the comments over to the users' respective accounts after users are imported via the API.
So to summarize the easiest path to take for the migration is:
- Import comments.
- Avatars and other media is migrated automatically if using the Import UI in
Manage Data -> Imports.
- Avatars and other media is migrated automatically if using the Import UI in
- Setup Secure or Simple SSO.
- Let the migration happen per-user automatically when they log in for the first time.
- This usually adds less than a second to the page load time if the user has less than 50k comments.
If you're using our WordPress plugin then there is no code to write! Simply go to the plugin's Admin page, click SSO Settings, and then Enable.
This will take you to a single-button click wizard which will create your API key, send it over to your WordPress install and turn SSO on. We've consolidated this into a single button click for you.
Note that if you are installing the plugin for the first time you will have to follow up the setup process before you see the admin page with the SSO Settings button.
WordPress SSO - Moderators
Note that currently for the "Moderator" badge to show next to your moderators when they comment with the FastComments WordPress plugin, they must also be added as a Moderator in the FastComments dashboard, and have their email verified.
For Custom integrations, there are two options.
Option One - Secure SSO
With Secure SSO, FastComments knows that the user commenting, voting, and reading comments is a real user on your site.
As long as you create a valid payload, the user will always have a seamless commenting experience.
With Secure SSO, the SSO payload is created server-side using HMAC authentication and then passed to the widget on the client.
With Secure SSO, the user's account is completely separate from the rest of the FastComments user-base. This means if we have two partners Company A and Company B, each can have an SSO user with the username "Bob".
- Some basic knowledge around backend development.
- Some basic knowledge around dealing with secret API keys.
- Some basic knowledge around API development or server-side rendering.
- Seamless commenting experience.
- Requires backend development.
Updating User Data
With Secure SSO, each time you pass the sso user payload, we will update their user with the latest information. For example, if
the user has a username
X, and you pass
Y in the SSO payload, their username will become
If you want to remove values using this approach then set them to
Secure SSO API
We also provide an API for interacting with the SSO users. See the docs.
Note that when using Secure SSO, users are automatically created behind the scenes on page load. You do not have to bulk import your users.
Option Two - Simple SSO
The alternative to Secure SSO is to simply pass the user information to the commenting widget.
Providing an email with Simple SSO is not required, however without this their comments will show as "Unverified".
Note! As of early 2022 usernames with Simple SSO do not need to be unique across all of FastComments.com.
Ideally, Simple SSO should only be picked when developing on a platform that doesn't provide backend access.
- Some basic knowledge around client-side development.
- Have to know at least the user's email.
- All activity still gets verified.
- The user never enters their username or email.
- Less secure than Secure SSO as the client side payload could be crafted to become any user.
Simple SSO API
Users automatically created via the Simple SSO flow are stored as
SSOUser objects. They can be accessed and managed via the
SSOUser API. See the docs.
With Simple SSO, we can provide the commenting widget with information about the user so that they don't have to enter their username or email to comment.
We can configure Simple SSO as follows:
The user will be logged in, and will create an SSO User behind the scenes. The user will have
createdFromSimpleSSO set to
true if fetched from the API.
- Email is the unique identifier for Simple SSO.
- Providing an email with Simple SSO is not required, however by default their comments will show as "Unverified". If no email is provided, the user cannot be fully authenticated.
- NEW Since Jan 2022: Usernames do not have to be unique across all of fastcomments.com
- Simple SSO can automatically create and update SSO users, if an email is provided, and the user was not originally created from Secure SSO.
The biggest differences between Disqus and FastComments Secure SSO is that Disqus uses SHA1 for encryption while we use SHA256. This means migrating from Disqus is easy - change the hashing algorithm used from SHA1 to SHA256 and update the property names passed to the UI.
Commento uses a drastically different SSO approach - they require you to have an endpoint that they invoke to authenticate the user. FastComments is the other way around - simply encode and hash the user's information using your secret key and pass it along.
All libraries for the comment widget (currently Angular, React, Vue) support callbacks.
The callbacks are specified in the configuration object, with the same signature for each library.
The callbacks supported are:
The exact signatures can be found in the TypeScript definitions.
Here's an example with all callbacks used:
The current page title is associated with the specified urlId and saved for use in moderation tools.
By default, this is retrieved from document.title.
If desired, your own page title can be specified as follows:
The comment count displayed at the top of the comment widget can either show all "top-level" comments, meaning those replies that are replies directly to the page or article itself, or it can be a count of all nested comments.
By default, this is
true - it is a count of the latter - all comments. In older versions of the comment widget the
default value is
We can change the behavior, so that it is a count of all nested comments by setting the countAll flag to true.
If we wanted the count to reflect only the top level comments, we set the flag to false.
This currently cannot be customized without code changes.