@updateddev/widget

Release notes widget for Updated.dev - Display beautiful release announcements in your app.

Features

• Lightweight - Only ~12KB (gzipped), actual widget loads from CDN
• Zero dependencies - No runtime dependencies, React is optional
• Multiple integrations - React component, vanilla JS, or script tag
• Next.js support - Works with App Router ("use client" included)
• Theme support - Light, dark, and auto (system) themes
• Mobile responsive - Toast notifications on mobile, modal on desktop
• User tracking - Track which users have seen releases
• TypeScript - Full type definitions included

Installation

npm / yarn / pnpm

npm install @updateddev/widget
# or
yarn add @updateddev/widget
# or
pnpm add @updateddev/widget

Script Tag (CDN)

<script
  src="https://widget.updated.dev/v1.js"
  data-key="your-client-key"
></script>

Quick Start

React / Next.js (with Provider - Recommended)

import {
  UpdatedWidgetProvider,
  useUpdatedWidget
} from '@updateddev/widget/react';

// App.tsx - Wrap your app with the provider
function App() {
  return (
    <UpdatedWidgetProvider
      clientKey="wk_xxx"
      position="bottom-right"
      theme="auto"
    >
      <MyComponent />
    </UpdatedWidgetProvider>
  );
}

// Any child component can use the hook
function MyComponent() {
  const { openReleaseNoteList, openLastReleaseNote, close } = useUpdatedWidget();

  return (
    <button onClick={openReleaseNoteList}>
      What's New
    </button>
  );
}

React / Next.js (Standalone)

import { UpdatedWidget } from '@updateddev/widget/react';

function App() {
  return (
    <UpdatedWidget
      clientKey="wk_xxx"
      position="bottom-right"
    />
  );
}

Vanilla JavaScript

import { UpdatedWidget } from '@updateddev/widget';

// Initialize
UpdatedWidget.init({
  clientKey: 'wk_xxx',
  position: 'bottom-right',
  theme: 'auto',
});

// Control the widget
UpdatedWidget.open();        // Open latest release
UpdatedWidget.openHistory(); // Open release history
UpdatedWidget.close();       // Close the widget
UpdatedWidget.destroy();     // Remove widget from DOM

Script Tag

<script
  src="https://widget.updated.dev/v1.js"
  data-key="wk_xxx"
  data-position="bottom-right"
  data-theme="auto"
></script>

<script>
  // Programmatic control via global API
  window.UpdatedWidget.openReleaseNoteList();
  window.UpdatedWidget.openLastReleaseNote();
  window.UpdatedWidget.close();
</script>

Configuration

React Props / Vanilla JS Config

| Option | Type | Default | Description | |--------|------|---------|-------------| | clientKey | string | required | Your widget client key from Updated.dev | | position | string | "bottom-right" | Position: "bottom-right", "bottom-left", "top-right", "top-left", "center" | | theme | string | "auto" | Theme: "light", "dark", "auto" | | autoOpen | boolean | true | Auto-open modal when new releases are available | | autoOpenDelay | number | 1500 | Delay before auto-open (ms) | | limit | number | 10 | Maximum number of releases to fetch | | userId | string | - | User ID for server-side seen tracking | | email | string | - | User email (adds user to audience) | | name | string | - | User display name | | debug | boolean | false | Enable debug logging | | useMockData | boolean | false | Use mock data (requires debug: true) | | apiUrl | string | - | Override API backend URL | | scriptUrl | string | - | Override script URL (for development) | | offsetTop | number | 0 | Top offset in pixels (desktop only) | | offsetRight | number | 0 | Right offset in pixels (desktop only) | | offsetBottom | number | 0 | Bottom offset in pixels (desktop only) | | offsetLeft | number | 0 | Left offset in pixels (desktop only) |

Script Tag Attributes

| Attribute | Description | |-----------|-------------| | data-key | Your widget client key (required) | | data-position | Widget position | | data-theme | Theme setting | | data-auto-open | Auto-open behavior ("true" / "false") | | data-user-id | User ID for tracking | | data-email | User email | | data-name | User display name | | data-debug | Enable debug mode |

API Reference

useUpdatedWidget Hook

Use this hook inside UpdatedWidgetProvider to control the widget from any component:

const { openLastReleaseNote, openReleaseNoteList, close } = useUpdatedWidget();

| Method | Description | |--------|-------------| | openLastReleaseNote() | Open the modal showing the latest release | | openReleaseNoteList() | Open the modal showing release history | | close() | Close the modal | | setOffset(offset) | Set widget position offset (desktop only) |

Vanilla JS API

| Method | Description | |--------|-------------| | UpdatedWidget.init(config) | Initialize the widget with configuration | | UpdatedWidget.open() | Open the latest release | | UpdatedWidget.openHistory() | Open the release history list | | UpdatedWidget.close() | Close the widget | | UpdatedWidget.destroy() | Remove widget and clean up | | UpdatedWidget.setOffset(offset) | Set widget position offset (desktop only) |

Global API (Script Tag)

window.UpdatedWidget.openLastReleaseNote();
window.UpdatedWidget.openReleaseNoteList();
window.UpdatedWidget.close();

User Identification

Track which users have seen releases:

// React with Provider
<UpdatedWidgetProvider
  clientKey="wk_xxx"
  userId={user.id}
  email={user.email}
  name={user.name}
>
  <MyComponent />
</UpdatedWidgetProvider>

// Vanilla JS
UpdatedWidget.init({
  clientKey: 'wk_xxx',
  userId: user.id,
  email: user.email,
  name: user.name,
});

• With userId: Seen status is synced across devices
• Without userId: Falls back to localStorage (device-specific)

Theming

// Auto-detect system preference
<UpdatedWidgetProvider theme="auto">

// Force light mode
<UpdatedWidgetProvider theme="light">

// Force dark mode
<UpdatedWidgetProvider theme="dark">

TypeScript

Full TypeScript support with exported types:

// React types
import type {
  UpdatedWidgetProps,
  UpdatedWidgetRef,
  UpdatedWidgetProviderProps,
  Release
} from '@updateddev/widget/react';

// Vanilla JS types
import type {
  UpdatedWidgetConfig,
  Release
} from '@updateddev/widget';

Error Handling

The widget provides helpful console messages for common issues:

| Error | Message | |-------|---------| | Missing clientKey | [UpdatedWidget] clientKey is required. | | Hook outside Provider | [UpdatedWidget] useUpdatedWidget must be used within an UpdatedWidgetProvider. | | Method called with no releases | [UpdatedWidget] openReleaseNoteList() called but no releases available. | | useMockData without debug | [UpdatedWidget] useMockData={true} is set but debug mode is disabled. |

Browser Support

• Chrome / Edge 88+
• Firefox 78+
• Safari 14+

Debug Mode

Enable debug logging and mock data for development:

// React
<UpdatedWidgetProvider
  clientKey="wk_xxx"
  debug={true}
  useMockData={true}
>
  <MyComponent />
</UpdatedWidgetProvider>

// Vanilla JS
UpdatedWidget.init({
  clientKey: 'wk_xxx',
  debug: true,
  useMockData: true,
});

License

MIT - see LICENSE for details.