The embeddable widget
If you would rather not build anything, drop in these two lines. The widget is a custom element that renders into a shadow root, so it neither inherits your styles nor leaks into them.
<script src="https://api.changeloop.dev/widget.js" defer></script>
<changelogapp-widget
data-public-id="YOUR_PUBLIC_ID"
data-api="https://api.changeloop.dev"></changelogapp-widget>
Both attributes are required. data-public-id is your feed id, data-api is the origin the widget fetches from. If either one is missing the element writes an error to the console and renders nothing at all, which is the first thing to check if you see an empty space where it should be.
Add data-theme="dark" to the element for a dark rendering; your page can toggle it at runtime. For deeper styling the widget exposes CSS custom properties (--changelogapp-text, --changelogapp-bg, --changelogapp-accent and more) and ::part() names, which you set in your own stylesheet. The app previews both themes live under Settings, Public feed.
Add data-repos to show only some of your repositories, for example one product's changelog on that product's site when several products share one account. The value is a comma-separated list of full names, owner/repo; a bare name matches nothing and renders an empty feed with no error. Up to ten repositories are honoured. A scoped widget shows Updates and Feedback only, because the roadmap has no per-repository view, and feedback is still filed where your team's feedback target points. Settings, Public feed has a picker that writes the attribute for you.
It renders three tabs in this order: Updates, Roadmap and Feedback. The first two read the feeds above. The third posts to the endpoint below and keeps each submission id in localStorage, so a visitor can come back and see what happened to what they sent.
The script is served versioned. /widget.js always serves the newest build and is cached for an hour, so a release reaches your visitors without you touching anything. /widget-vN.js pins one build: once a version number has been served its bytes never change again, and it is cached for a year. Pin it if you would rather adopt changes on purpose.
Load exactly one widget script per page
The two URLs are alternatives, not layers. Both register the same custom element name, and a browser lets a name be registered only once per document: whichever script executes first wins, for the life of the page, and the second one is inert. So a page carrying both /widget.js and /widget-v5.js renders whichever the browser happened to run first, which is not something you control, and adding /widget-v5.js next to an existing /widget.js to pin the version does nothing at all. It is the older build that usually wins, because it is the one already in cache.
When it happens the widget writes a warning to the console naming both builds, so you are not left guessing. It cannot do more than warn: by the time the second copy runs, the first has already claimed the name. The fix is always to replace the script tag rather than add another one, and the same applies if a tag manager or a partial injects one for you. To move from the rolling build to a pinned one, change the src.
Release pop-up
Add data-mode="popup" and the element renders no tabs. When a visitor has something new to see, it shows one small card with your newest release, and nothing at all otherwise. data-mode is not case-sensitive.
<script src="https://api.changeloop.dev/widget.js" defer></script>
<changelogapp-widget
data-public-id="YOUR_PUBLIC_ID"
data-api="https://api.changeloop.dev"
data-mode="popup"
data-changelog-url="https://feed.changeloop.dev/feed/YOUR_PUBLIC_ID"></changelogapp-widget>
On wide screens the card sits in the bottom-left corner, because the bottom-right corner usually belongs to a chat launcher. On screens under 480px wide it spans the full width and covers a chat launcher until it is closed. It opens in the browser's top layer, so a parent element's overflow, transform or z-index cannot clip or bury it. To move it, style ::part(popup).
Each release is shown once. The card appears when the visitor has entries they have not seen yet. It shows the newest of them, with a count when there are several, and counts them as seen the moment it appears. The next page load shows nothing until you publish again.
A first visit shows nothing at all: the widget only notes how far your changelog goes, so existing users are not greeted with old news on the day you add it. The card starts with your next release. A visitor who already read a release in the inline widget is not shown it again.
What a visitor has seen is kept in localStorage, not in a cookie, so it belongs to one browser and one site origin. The same person on another of your domains starts again from a first visit. If the browser blocks storage, every visit counts as a first visit and the card never shows.
data-changelog-url is optional. With an http or https address, the card gets a See all updates link to it, usually your hosted page or your own changelog page. With anything else, no link is drawn. data-theme and data-repos work exactly as they do on the inline widget.
The card never takes focus and never blocks the page: it is a labelled region, not a dialog. It closes with its close button, or with Escape while focus is inside the card. Escape anywhere else on your page is left to your own code.
The rule of one widget script per page still applies. The pop-up and the inline widget can share a page: load the script once and add both elements, and they agree on what the visitor has already seen.
Pinned builds up to /widget-v18.js are older than the pop-up. They ignore data-mode and render the inline tabs instead, so use /widget.js or a newer pinned build.
In the app, Settings, Public feed has this snippet ready to copy, with your feed id, theme and repository scope filled in. Views of the card and clicks on its Learn more link appear under Analytics as their own numbers.
Emoji reactions
Readers can react to an entry without writing anything. With reactions on, every entry ends with a row of five, 👍 🎉 ❤️ 🚀 👀, each with its count. The row shows in the inline widget, on the release pop-up card and on the hosted feed page.
Reactions are off until you turn them on in the app, under Settings, Public feed. Your embed code does not change: the widget reads the switch from your feed, so the row appears and disappears with it. Turning reactions off hides the row and keeps the counts, so they come back if you turn it on again. Pinned builds from before reactions existed never show the row.
Each reader can give an entry each reaction once, and pressing it again takes it back. The widget tells readers apart by a random id it creates in the browser on the first click, not by an account or an email address. We store only a hash of that id combined with your team, so the same browser leaves unrelated hashes on two different changelogs.
Counts are best effort: a friendly signal, not a vote. Clearing browser storage or opening a private window lets someone react again, so never base a decision that matters on them. The counts in your feed can also run a few minutes behind, because the feed is cached, but the person who clicks sees their own reaction counted straight away. In the app, the Published tab of the inbox shows each entry's total.
Reacting keeps two things in the visitor's localStorage, never in a cookie. changelogapp-widget:reader-id holds the random id, one per browser and site origin. changelogapp-widget:reactions: followed by your feed id holds the reactions this browser chose, for up to 200 entries, the ones it reacted to most recently. The hosted page keeps the same two under its own address. If the browser blocks storage, reacting still works for that page view and is not remembered after it.
To style the row, use ::part(reactions), ::part(reaction) for each button and ::part(reaction-count) for its number, all listed under Styling below. A count of zero shows no number. A pressed button carries aria-pressed="true" and is drawn with a ring in your --changelogapp-accent colour and bold text. ::part() cannot select by that attribute, so set --changelogapp-accent to change how a pressed button looks.
Public feedback board
The board lets readers see what other people have asked for and vote on it. With the board on, the Feedback tab opens with your most-voted requests, each with its status, and the usual form sits below them.
The board is off until you turn it on in the app, under Settings, Public feed. Your embed code does not change: the widget reads the switch from your feed. Turning the board off hides it and keeps your requests and their votes. It lives in the Feedback tab, so a widget that shows no Feedback tab shows no board either.
The board shows only what you write. A visitor's feedback never goes on it by itself: you decide which requests go on the board, and you write each one's title and description yourself, on the Feedback board page in the app. You can start a request from a message a visitor sent or post an idea of your own, and the board never shows the visitor's message or email address. The board shows your top 100 requests, and a team can keep up to 500.
Each request has one of five statuses: Under consideration, Planned, In progress, Shipped or Declined. Link a request to an update and it moves to Shipped by itself when that update is published, or straight away if it already is. A request you started from a visitor's message also moves to Shipped when an update that delivers that message is published.
Each browser has one vote per request on each site, and clicking again takes it back. Voting closes once a request is Shipped or Declined, though anyone who already voted can still take their vote back. Votes are a signal, not a headcount: clearing browser storage or opening a private window lets someone vote again, so use them to see what people care about, never to settle a decision that matters. The counts other visitors see can run a little behind, while the visitor who votes sees the exact new count.
Voting keeps two things in the visitor's localStorage, never in a cookie. changelogapp-widget:votes: followed by your feed id lists the requests this browser has voted on, up to the 200 most recent. changelogapp-widget:reader-id is the random id the reactions use, one per browser and site origin, so voting creates nothing new if the visitor has already reacted. We store only a hash of that id combined with your team, never the id itself, so the same browser leaves unrelated hashes on two different changelogs. We do not store the visitor's IP address with a vote. If the browser blocks storage, voting still works for that page view and is not remembered after it.
The board never shows in the release pop-up, and not on a widget scoped with data-repos either, because it covers your whole team. Your hosted changelog page has a Requests tab with the same board, a filter by status, and votes that count the same way. The board is also public JSON, at GET /v1/public/YOUR_PUBLIC_ID/board.json on the same API, which answers 404 while the board is off.
To style the board, use ::part(board) for the whole block and ::part(board-heading) for its heading, then the parts of each request, all listed under Styling below. The vote button, ::part(board-vote), carries aria-pressed="true" once this browser has voted, and is then drawn with a ring in your --changelogapp-accent colour. ::part() cannot select by that attribute, so set --changelogapp-accent to change how a counted vote looks.
Styling
The widget renders into a shadow root, so most of your stylesheet does not reach inside it. Inherited properties still flow in where the widget does not set its own, and so do the custom properties below, set on the element or on an ancestor. For anything else, use the ::part() names below. Both lists are a stable interface: once a name has shipped it is never renamed.
Custom properties
--changelogapp-font-family--changelogapp-text--changelogapp-text-muted--changelogapp-bg--changelogapp-border--changelogapp-accent--changelogapp-radius--changelogapp-space--changelogapp-timeline-line--changelogapp-pill-bg--changelogapp-pill-text
Tag pills. A tag with a colour uses it as the background, and in both themes the text colour is picked to read on that background, at 4.5:1 or better. White is preferred whenever it reaches that. A colour the widget cannot read as a solid RGB value gets no picked text colour and keeps the theme's default. To choose the text colour yourself, in either theme, set --changelogapp-pill-text. A ::part(entry-tag) rule wins over everything, so if you set a background there, set color too. --changelogapp-pill-bg is the background of a tag that has no colour. Pinned builds up to /widget-v18.js keep white pill text in the light theme.
Parts
- Changelog entries:
month-heading,entry,entry-date,entry-tag,entry-title,entry-body,entry-link,timeline-dot,entry-image,entry-header-image - Inside an entry body:
entry-body-heading,entry-body-paragraph,entry-body-list,entry-body-list-item,entry-body-link,entry-body-code - The unread count on the Updates tab:
unread-badge - The release pop-up:
popup,popup-heading,popup-close,popup-link - The Get updates by email form, at the top of Updates when email subscribers are switched on (Team plan):
subscribe,subscribe-heading,subscribe-input,subscribe-button,subscribe-status - Emoji reactions, when they are switched on:
reactions,reaction,reaction-count - The public feedback board, when it is switched on:
board,board-heading,board-request,board-request-title,board-request-description,board-request-status,board-request-link,board-vote,board-vote-count
Content-Security-Policy
If your site sends a Content-Security-Policy header, the widget needs the API origin in two directives. script-src lets the script load. connect-src lets it read your changelog, send feedback and record views. With only the first, the element appears and then stays empty, which looks like a broken feed rather than a blocked request. The pop-up needs the same two.
script-src https://api.changeloop.dev; connect-src https://api.changeloop.dev;From widget 0.16.0, which /widget.js serves, current browsers need no style-src change: the widget hands its styles over as a constructed stylesheet, which style-src does not govern. Older builds, including pinned builds up to /widget-v18.js, and browsers without constructable stylesheets use a style element instead, which needs style-src 'unsafe-inline'.
img-src is only needed if you have turned images on in the app, under Settings, Public feed, Images. The widget then loads pictures straight from your image hosts, and a policy that does not list them blocks every one. Settings prints the exact line with img-src filled in from your list, so copy it again whenever you change the list. GitHub's screenshot hosts also need https://github-production-user-asset-6210df.s3.amazonaws.com in img-src, because a GitHub screenshot link redirects there and the browser checks that address too.
If your policy sets only default-src, add both directives and repeat your default-src sources in each. A script-src or connect-src replaces default-src for scripts or connections, so leaving your own sources out would block them.
Add the origin to your existing directives rather than replacing them. Settings, Public feed in the app shows this line with the right origin for your account. If you do not send that header, there is nothing to do.
The hosted feed page
We host a plain page at that address too: your changelog and your roadmap board, rendered from the same two feeds above. It needs no sign-in and nothing set up on your side. It is also where we send people back once a loop closes: the Shipped comment we leave on a GitHub issue links here, and so does shippedEntry.link from the submission lookup above, both landing on the entry that shipped with its own #entry-ID anchor, which still finds the entry even if it has since moved to a later page.
Treat it as a fallback, not the integration. The changelog feed and the widget are still the way to put this into your own site so it looks like your product rather than ours; this page is for when you have not done that yet, and for loop-close links, which point here regardless of what else you have built.
Your changelog, inside your product
Changeloop drafts each entry from a merged pull request, holds it for your review, and serves it to this widget and to a JSON feed. Free for one repository, no card.
Start free