changelogdev-widget

An embeddable changelog widget for any website. Show your users what's new with a single line of code.

Zero dependencies. Framework-agnostic. Built as a Web Component with Shadow DOM for complete style isolation.

Demo

A floating bell icon appears in the bottom-right corner of your page. When clicked, it slides open a panel showing your latest changelog entries. Unread entries show a notification badge.

Quick Start

Script Tag (simplest)

Drop this into any HTML page:

<script src="https://unpkg.com/changelogdev-widget"></script>
<changelog-widget project-id="your-project-id"></changelog-widget>

That's it. A floating bell icon appears in the bottom-right corner. Click it to see your changelog.

npm

npm install changelogdev-widget

Option A: Declarative (HTML element)

import 'changelogdev-widget'

// In your HTML or JSX:
<changelog-widget project-id="your-project-id" theme="dark" />

Option B: Programmatic

import { init } from 'changelogdev-widget'

init({
  projectId: 'your-project-id',
  position: 'bottom-right',
  theme: 'dark',
  accentColor: '#6366f1',
})

React / Next.js

The widget works out of the box with React. Import once and use the custom element:

import 'changelogdev-widget'

export default function App() {
  return (
    <div>
      <h1>My App</h1>
      <changelog-widget
        project-id="your-project-id"
        theme="auto"
        accent-color="#6366f1"
      />
    </div>
  )
}

For TypeScript, add this declaration to avoid JSX type errors:

// global.d.ts
declare namespace JSX {
  interface IntrinsicElements {
    'changelog-widget': React.DetailedHTMLProps<
      React.HTMLAttributes<HTMLElement> & {
        'project-id'?: string
        'api-url'?: string
        position?: 'bottom-right' | 'bottom-left'
        theme?: 'light' | 'dark' | 'auto'
        'accent-color'?: string
      },
      HTMLElement
    >
  }
}

Vue

<template>
  <changelog-widget project-id="your-project-id" theme="dark" />
</template>

<script setup>
import 'changelogdev-widget'
</script>

Configuration

All configuration is done through HTML attributes or the init() options object.

| Attribute | Option | Default | Description | | --------------- | -------------- | ---------------------------------------------- | ---------------------------------- | | project-id | projectId | (required) | Your project ID from Changelog.dev | | api-url | apiUrl | https://www.changelogdev.com/api/widget | API endpoint for fetching entries | | position | position | bottom-right | Widget position on screen | | theme | theme | auto | light, dark, or auto | | accent-color | accentColor | #6366f1 | Primary color for the trigger button |

Features

• Zero dependencies -- no React, no Vue, no nothing. Pure Web Components.
• Shadow DOM isolation -- styles never leak in or out. Works on any page.
• Unread badge -- tracks which entries the user has seen via localStorage.
• Responsive -- works on mobile, adapts to small screens.
• Theme support -- light, dark, or auto (follows system preference).
• Keyboard accessible -- Escape to close, focusable trigger button.
• Mock data fallback -- works offline or without an API for demos.
• Tiny footprint -- under 8KB gzipped.

API Response Format

The widget expects your API to return JSON in one of these shapes:

[
  {
    "id": "entry-1",
    "title": "New Feature: Dark Mode",
    "description": "You can now switch between light and dark themes.",
    "type": "feature",
    "date": "2026-03-01",
    "url": "https://example.com/blog/dark-mode"
  }
]

Or wrapped:

{
  "entries": [...]
}

Entry fields:

| Field | Type | Required | Values | | ------------- | -------- | -------- | ------------------------------------------------- | | id | string | Yes | Unique identifier | | title | string | Yes | Entry title | | description | string | Yes | Entry description (plain text) | | type | string | Yes | feature, improvement, fix, announcement | | date | string | Yes | ISO date string (YYYY-MM-DD) | | url | string | No | Link to full entry |

Why Web Components?

• No framework lock-in -- works with React, Vue, Svelte, Angular, or plain HTML
• Shadow DOM -- styles are completely isolated; no CSS conflicts with your app
• Native browser API -- no runtime dependencies, no virtual DOM overhead
• Future-proof -- Web Components are a web standard, not a library that can be deprecated

Development

npm install
npm run build    # Build ESM + CJS + IIFE
npm run dev      # Watch mode
npm run typecheck

Changelog.dev

This widget is the open-source companion to Changelog.dev -- a hosted changelog platform for SaaS products. Create beautiful changelog pages, generate entries with AI, and embed this widget to keep your users informed.

Create a free changelog ->

License

MIT -- see LICENSE.

Built by Changelog.dev.