Comments

Hyvor Talk's main feature is the comments embed. It is a fully-featured real-time commenting system that can be embedded on blogs, news sites, and other websites.

The comments embed is loaded via the <hyvor-talk-comments> Web Component. Go get started, add the following script right before the </body> tag. It registers the <hyvor-talk-comments> Web Component on your webpage.

<script async src="https://talk.hyvor.com/embed/embed.js" type="module"></script>

Then, add the <hyvor-talk-comments> element to the place where you want the comments section to load. It is possible to add multiple comments sections to a single page if needed.

<hyvor-talk-comments website-id="YOUR_WEBSITE_ID" page-id=""></hyvor-talk-comments>

For platform-specific instructions, see the Install page.

Attributes

The following attributes are supported in the <hyvor-talk-comments> element

Attribute

Value

website-id

Your Hyvor Talk Website ID

page-id

A unique identifier for the current page. See page-id.

page-url

Page URL (optional).

page-title

Page title (optional). The page title is shown in notifications, emails, and in the Console. document.title is used by default.

page-language

Override the website's language for this page. See languages.

page-author

Email (or base64 encoded email) of the author

page-badges

Assign page-level badges for users

sso-user and sso-hash

See Stateless Single Sign-on

colors

light, dark, or os. See Styles & Colors

loading

Accepts default, lazy, and manual. See loading

settings

JSON encoded settings. See settings

t-*

Set custom texts. See translations

page-id

The page-id attribute is used to identify the current page, and it is perhaps the most important attribute.

If it is not set or empty, the canonical URL of the current page will be used as the page-id.
If it is set, the value will be used as the page-id.

Each page-id will load a different thread. It is highly recommended to use an ID that does not change over time (e.g. a database ID). If an ID change, you will need to migrate data to the new page manually. See our moving data between pages.

page-badges

The page-badges attribute is used to assign badges to users at the page level. This is useful, for example, to give a badge to the author of the page. It accepts a JSON-encoded string:

<hyvor-talk-comments
	website-id="x"
	page-badges='{
		"sso:user-id": 3,
		"htid:hyvor_x": 1,
		"htid:sso_x": 2
	}'
></hyvor-talk-comments>

Each key in the JSON object is a user ID, which can be of two types.

sso:<id> - SSO user ID on your end. <id> is the id attribute in the SSO User Object.
htid:<htid> - Hyvor Talk user ID, which can be found in the Console API User Object.

The value of the JSON object is a badge ID which can be found at Console → Settings → Badges.

settings

All website-level settings can be overridden at the page level using the settings attribute. It accepts a JSON-encoded string. Here is an example:

<hyvor-talk-comments
	website-id="x"
	settings='{
		"custom_css":"#app { font-size: 18px }",
		"profiles": {
			"pictures": false
		}
	}'
></hyvor-talk-comments>

Here are all the available settings:

comments.settings = {
	name: 'John Doe', // website name
	custom_css: null, // or string of CSS
	auth: {
		sso_stateless_login_url: null // or URL string
	},
	comments_view: {
		note: 'This is a note', // note shown above the comments
		close_after_days: 0, // close the page after X days (0 for never)
		is_keyboard_navigation_on: true,
		nested_levels: 3, // number of nested levels (the rest will be collapsed)
		display_replied_to_type: 'none' | 'deep' | 'all' // when to show 'replied to' tag
	},
	profiles: {
		default_sort: null, // 'top' | 'newest' | 'oldest'
		pictures: true, // show profile pictures
		profiles: true, // show profile popup
		default_picture: null, // default profile picture URL
		display_name_type: 'name', // 'name' | 'username'
		mod_alias_name: 'Moderator', // alias for moderators for company representation
		mod_alias_picture: null,
		mod_badge_id: null // for showing a special badge for moderators
	},
	realtime: {
		on: true, // enable realtime updates
		count: true, // show online count
		users: false, // show online users list
		typing: 'off' // show if someone is typing = 'off' | 'on_without_typer' | 'on_with_typer'
	},
	voting: {
		type: 'both', // 'both' | 'up' | 'down'
		voters: true // show voters list
	},
	top_widget: 'reactions', // 'reactions' | 'ratings' | 'none'
	reactions: {
		configs: [
			{
				type: 'superb', // 'superb' | 'love' | 'wow' | 'sad' |  'laugh' | 'angry'
				is_shown: true,
				image_url: 'image.png',
				text: 'Superb'
			}
			// more items
		],
		display_type: 'image' // how to display reaction = 'image' | 'text' | 'both'
	},
	ratings: {
		star_color: '#f1c40f' // color of the rating stars
	},
	text: {
		// if a string is set, it will be shown *regardless* of the language.
		comment_box: null,
		reply_box: null,
		no_comments: null,
		reactions: null,
		ratings: null,
		comment_count_0: null,
		comment_count_1: null,
		comment_count_multi: null
	},
	editor: {
		emoji: true,
		images: true,
		gifs: true,
		embeds: true, // link embedding
		mentions: true,
		code_blocks: true,
		blockquotes: true,
		inline_styles: true, // bold, italic, inline code, strike, spoiler
		links: true,
		math: true
	},
	ui: {
		width: null, // null | number - width of the comments box in pixels, 100% if null
		box_shadow: 'string', // box-shadow CSS property for boxes
		box_radius: 'string', // border-radius CSS property for boxes
		box_border_size: 'string', // border-size CSS property for boxes
		box_border_color: 'string', // border-color CSS property for the comments and other boxes
		button_radius: 'string', // border-radius CSS property for buttons
		color_theme: 'os' | 'light' | 'dark' // default color theme
	},
	light_palette: {
		text: '#000000',
		accent: '#000000',
		accent_text: '#000000',
		box: '#000000',
		box_text: '#000000',
		box_text_light: '#000000',
		input: '#000000'
	},
	dark_palette: {}, // same properties as light_palette

	// comments highlighting
	highlight: {
		new: true, // whether to highlight new comments
		new_color: '#00ff00',
		// upvote-based highlighting
		upvote_1_threshold: null, // null | number
		upvote_2_threshold: 2, // null | number
		upvote_1_color: '#0000ff',
		upvote_2_color: '#ff0000'
	}
};

t-* (custom translations)

You can set custom translations using the t- attributes.

<hyvor-talk-comments t-as-guest="Comment without account" t-newest="Latest" />

You can find the keys on the translation page (login required). For example, if the key is as-guest, the attribute should be t-as-guest. See language documentation for more information.

If you need to dynamically build a translation based on additional context, use the t hook. For certain translations, it provides additional context like comment or user data.

Creating the Component with JavaScript

Instead of adding the <hyvor-talk-comments> element directly to the HTML, you can create it with JavaScript. This is useful when you need to use properties.

const comments = document.createElement('hyvor-talk-comments');
comments.setAttribute('website-id', 'YOUR_WEBSITE_ID');
comments.setAttribute('page-id', page.id);

document.body.appendChild(comments);

Properties (Deprecated)

Properties are deprecated. Use settings attribute and t- attributes instead.

1. Settings (Deprecated)

The settings property does the same thing as the settings attribute. This is only supported for backward compatibility.

Note that in order to make settings property work, you should wait until the Web Component is defined. The easiest method is to use customElements.whenDefined.

customElements.whenDefined('hyvor-talk-comments').then(() => {
	// create the element
	const comments = document.createElement('hyvor-talk-comments');
	// set the settings
	comments.settings = {};
	// then append
	document.getElementById('wrap').appendChild(comments);
});

2. Translations (Deprecated)

This property is only supported for backward compatibility. We recommend using t- attributes for translations for new users.

const comments = document.createElement('hyvor-talk-comments');

comments.translations = {
	sort: 'Order by',
	reactions_text: 'What do you think about this post?'
};

Loading

By default, the comments section is loaded as soon as the commponent is added to the DOM. You can customize this behavior using the loading attribute. It accepts the following values:

default - start loading immediately
lazy - start loading when the element is in the viewport (using IntersectionObserver)
manual - start loading when .load() is called on the <hyvor-talk-comments> element.

Manual Loading

The loading attribute can be set to manual to delay the rendering of the comments embed until the .load() method is called. Here is an example with a button to load the comments:

<hyvor-talk-comments website-id="YOUR_WEBSITE_ID" page-id="" loading="manual"></hyvor-talk-comments>

<button onclick="document.querySelector('hyvor-talk-comments').load()">Load Comments</button>

API

The <hyvor-talk-comments> element exposes a mini-API with the following methods:

api.reload() - reload the comments section. Same as .load()
api.page() - get current page data. See Page Object.
api.auth.user() - get the current user's public data. See User Object. null if not logged in.
api.auth.logout() - logout the current user. Removes the login storage from the localStorage.
api.hooks.register(name: string, value: Record<string, any>) - Register a hook.

Here is an example of how to get the current user's data:

const comments = document.querySelector('hyvor-talk-comments');
comments.api.auth.user();

API Objects

Page Object

interface Page {
	id: number;
	created_at: number;
	identifier: string;
	url: string;
	title: string;
	is_closed: boolean;
	is_premoderation_on: boolean;
	comments_count: number;
	reactions: Record<'superb' | 'love' | 'wow' | 'sad' | 'laugh' | 'angry', number>;
	ratings: {
		average: number;
		count: number;
	};
	online_count: number;
}

User Object

interface User {
	id: number;
	type: 'hyvor' | 'sso';
	name: string;
	username: string;
	picture_url: string | null;
	bio: string | null;
	location: string | null;
	website_url: string | null;
	badges: number[];
}