Add the comment widget

The Quipthread embed widget is a small script that loads the comment widget from your Quipthread instance. It reads configuration from data-* attributes on a container element marked with data-quipthread.

Basic usage

<div
  data-quipthread
  data-site-id="YOUR_SITE_ID"
  data-page-id="YOUR_PAGE_ID"
></div>
<script
  src="https://your-quipthread-instance.com/embed.js"
  async
></script>

The script discovers your Quipthread instance automatically from the src URL — no separate API URL configuration needed.

Container element

The widget mounts into every element with the data-quipthread attribute when the page loads. All configuration is placed as data-* attributes on this element. The element can come before or after the script.

Note

Earlier versions used <div id="comments">. That markup still works when the element has data-site-id. A #comments element without it, such as a WordPress theme’s native comment section, is left alone.

Attributes

Required

Attribute	Description
data-site-id	The site ID from your Quipthread dashboard.
data-page-id	A unique identifier for the current page (e.g. post slug, URL path). Comments are scoped to this value.

Optional

Attribute	Default	Description
data-page-url	—	The canonical URL of the page. Stored with comments for reference in the dashboard.
data-page-title	—	The title of the page. Stored with comments for display in the dashboard.
data-lang	en	UI language for the widget. English (en) is currently the only language; other values fall back to it.
data-theme	—	Theme preset name. If omitted or set to auto, follows the theme configured in the dashboard for this site, falling back to system preference. See Theming.
data-qt-*	—	Overrides for individual colors, corner radii, and the font. See Theming.

Theme override

If you set data-theme on the container element, it takes priority over the site’s dashboard theme setting. Set it to auto to revert to the dashboard setting with a system-preference fallback.

The widget also observes changes to data-theme on the container element at runtime, so you can drive theme switching from your own page-level toggle by updating the attribute.

Script placement

The async attribute is recommended. The script defers mounting until DOMContentLoaded if the DOM is not yet ready.

<script src="https://your-instance.com/embed.js" async></script>

embed.js is a few hundred bytes. It loads the widget from the same origin, and the comment editor only loads when a reader starts writing.

Note

The script finds your instance from its own src URL, so load it with a <script> element: in your HTML, or created with document.createElement('script'). Bundling embed.js into your own JavaScript does not work.

If your site sends a Content Security Policy, allow your Quipthread origin in script-src (for embed.js and the modules it loads) and connect-src (for the API).

Single-page apps

In apps that change pages without a full reload (Next.js, Vue, Nuxt, SvelteKit, and similar), mount the widget from JavaScript so it follows navigation. embed.js defines window.Quipthread as soon as it runs:

const widget = window.Quipthread.mount(element, {
  siteId: 'YOUR_SITE_ID',
  pageId: location.pathname,
})

// After client-side navigation:
widget.update({ pageId: location.pathname })

// When the component that holds the element is removed:
widget.unmount()

mount(target, options) takes an element or a CSS selector. Options override the element’s data-* attributes:

Option	Attribute
siteId	data-site-id
pageId	data-page-id
pageUrl	data-page-url
pageTitle	data-page-title
lang	data-lang
theme	data-theme
vars	data-qt-* (for example { accent: '#c06020' } for data-qt-accent)

Mounting an element that already has a widget updates it instead of adding a second one. Changing siteId or pageId shows that page’s thread. window.Quipthread.scan() mounts any new data-quipthread elements on the page.

The dashboard’s Embed code shows ready-made components for Next.js, Vue, Nuxt, and Astro.

Voting

Readers can upvote comments. Voting is a toggle — clicking the upvote button again removes the vote. A user must be signed in to vote; the button is rendered for all users but requires authentication to submit.

No additional configuration is needed for voting.

Comment sort order

The widget displays comments sorted by newest first by default. Readers can switch between three sort modes using the sort bar above the comment list:

Mode	Description
Newest	Most recently posted comments first (default)
Oldest	Chronological order, oldest first
Top	Sorted by upvote count, descending

Sort preference is not persisted — it resets to newest on page reload.

Browser compatibility

Use a current version of Chrome, Firefox, Safari, or Edge. Internet Explorer is not supported.