version-pill-react

React components for VersionPill — changelog, roadmap & version badge widgets.

Install

npm install version-pill-react
# or
bun add version-pill-react

Quick Start

Version Badge (floating pill)

import { VersionPill } from "version-pill-react";

// Floating pill — shows version + opens changelog on click
<VersionPill projectId="your-project-slug" />

// With options
<VersionPill
  projectId="your-project-slug"
  position="bottom-right"       // "bottom-right" | "bottom-left" | "top-right" | "top-left"
  size="sm"                      // "sm" | "md" | "lg"
  accent="green"                 // "green" | "blue" | "purple" | "orange" | "neutral"
  theme="auto"                   // "auto" | "light" | "dark"
  showBranding={true}            // show "VersionPill" text
  onNewVersion={(v) => {}}       // callback when new version detected
  onClick={() => {}}             // custom click handler
  className=""                   // additional CSS classes
/>

Programmatic Control (ref)

Open the modal to a specific tab from external buttons — perfect for footer nav links.

import { useRef } from "react";
import { VersionPill, type VersionPillHandle } from "version-pill-react";

function Footer() {
  const vpRef = useRef<VersionPillHandle>(null);

  return (
    <footer>
      <VersionPill ref={vpRef} projectId="my-project" position="inline" />
      <nav>
        <button onClick={() => vpRef.current?.open("changelog")}>Changelog</button>
        <button onClick={() => vpRef.current?.open("roadmap")}>Roadmap</button>
        <button onClick={() => vpRef.current?.open("ideas")}>Feature Requests</button>
      </nav>
    </footer>
  );
}

VersionPillHandle methods: | Method | Description | |--------|-------------| | open(tab?) | Open the modal. Pass "changelog", "roadmap", or "ideas" to jump to that tab. | | close() | Close the modal. |

Inline Version Badge

import { VersionBadge } from "version-pill-react";

// Inline badge — renders where you place it (no portal/floating)
<VersionBadge projectId="your-project-slug" />

// With options
<VersionBadge
  projectId="your-project-slug"
  size="sm"                      // "sm" | "md" | "lg"
  accent="green"                 // "green" | "blue" | "purple" | "orange" | "neutral"
  theme="auto"                   // "auto" | "light" | "dark"
  href="/changelog"              // optional link
  className=""
/>

Changelog Widget

import { Changelog } from "version-pill-react";

<Changelog
  projectId="your-project-slug"
  maxHeight={400}                // scroll height in px
  theme="auto"                   // "auto" | "light" | "dark"
  className=""
/>

Roadmap Widget

import { Roadmap } from "version-pill-react";

<Roadmap
  projectId="your-project-slug"
  maxHeight={400}
  theme="auto"
  className=""
/>

useVersion Hook

import { useVersion } from "version-pill-react";

function MyComponent() {
  const { version, isLoading, error } = useVersion({
    projectId: "your-project-slug",
    refetchInterval: 60000,      // poll every 60s (optional)
  });

  if (isLoading) return <span>Loading...</span>;
  return <span>v{version?.version}</span>;
}

Props Reference

Common Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | projectId | string | required | Your VersionPill project slug | | baseUrl | string | "https://www.versionpill.com" | API base URL | | theme | "auto" \| "light" \| "dark" | "auto" | Color theme |

VersionPill Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | position | string | "bottom-right" | Floating position | | size | "sm" \| "md" \| "lg" | "md" | Badge size | | accent | string | "green" | Accent color | | showBranding | boolean | true | Show "VersionPill" text | | onNewVersion | (version) => void | — | New version callback | | onClick | () => void | — | Custom click handler |

VersionBadge Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | size | "sm" \| "md" \| "lg" | "md" | Badge size | | accent | string | "green" | Accent color | | href | string | — | Optional link URL |

Notes

• All components are "use client" — they use React hooks internally
• VersionPill uses createPortal to render as a floating overlay
• VersionBadge renders inline where you place it
• Components return null if the project has no published releases
• Wrap in <Suspense> for Next.js App Router compatibility:

import { Suspense } from "react";
import { VersionPill } from "version-pill-react";

<Suspense fallback={null}>
  <VersionPill projectId="your-project-slug" />
</Suspense>

License

MIT