Skip to content

Production-ready animations, transitions, backgrounds, and scenes for Remotion

feat: github stars

dev_wandry421702cb7a08
diff --git a/content/docs/meta.json b/content/docs/meta.json
index 455295df..fcf40c1c 100644
--- a/content/docs/meta.json
+++ b/content/docs/meta.json
@@ -7,6 +7,7 @@
"environment",
"ui-blocks",
"transitions",
+ "social",
"compositions"
]
}
diff --git a/content/docs/social/github-stars.mdx b/content/docs/social/github-stars.mdx
new file mode 100644
index 00000000..90efce18
--- /dev/null
+++ b/content/docs/social/github-stars.mdx
@@ -0,0 +1,158 @@
+---
+title: GitHub Stars
+description: Stargazer list fly-through with a synced odometer counter — renders standalone from sample data or accepts live stargazer props
+---
+
+<ComponentPreview name="github-stars" />
+
+## Installation
+
+<InstallBlock name="github-stars" />
+
+## Usage
+
+Standalone in a Remotion `<Composition>` — uses the built-in sample stargazers so the video renders immediately after install:
+
+```tsx
+// src/Root.tsx
+import { Composition } from "remotion";
+import { GitHubStars } from "@/components/remocn/github-stars";
+
+const GitHubStarsScene = () => (
+ <GitHubStars
+ repo="remotion-dev/remotion"
+ totalStars={24813}
+ accentColor="#f5a623"
+ orientation="horizontal"
+ speed={1}
+ theme="light"
+ />
+);
+
+export const RemotionRoot = () => (
+ <Composition
+ id="GitHubStars"
+ component={GitHubStarsScene}
+ durationInFrames={300}
+ fps={30}
+ width={1280}
+ height={720}
+ />
+);
+```
+
+### With live data
+
+Pass fetched stargazers to replace the built-in sample data. Each entry in `stargazers` drives one row in the fly-through:
+
+```tsx
+// src/Root.tsx
+import { Composition } from "remotion";
+import { GitHubStars } from "@/components/remocn/github-stars";
+
+// Shape returned by your fetch (e.g. from /api/stargazers)
+const stargazers = [
+ {
+ login: "octocat",
+ avatarUrl: "https://avatars.githubusercontent.com/u/583231",
+ starredAt: "2021-03-15T10:00:00Z",
+ },
+ // … more entries
+];
+
+const GitHubStarsScene = () => (
+ <GitHubStars
+ repo="remotion-dev/remotion"
+ totalStars={24813}
+ stargazers={stargazers}
+ orientation="horizontal"
+ accentColor="#f5a623"
+ speed={1}
+ theme="light"
+ />
+);
+
+export const RemotionRoot = () => (
+ <Composition
+ id="GitHubStars"
+ component={GitHubStarsScene}
+ durationInFrames={300}
+ fps={30}
+ width={1280}
+ height={720}
+ />
+);
+```
+
+## Props
+
+<PropsTable
+ rows={[
+ {
+ name: "repo",
+ type: "string",
+ default: "\"remotion-dev/remotion\"",
+ description: "Repository shown in the heading (owner/name format)",
+ },
+ {
+ name: "totalStars",
+ type: "number",
+ default: "24813",
+ description: "Total star count the odometer counts up to",
+ },
+ {
+ name: "stargazers",
+ type: "Stargazer[]",
+ default: "SAMPLE_STARGAZERS",
+ description: "Array of stargazer objects that populate the fly-through list. Falls back to built-in sample data when omitted.",
+ },
+ {
+ name: "orientation",
+ type: "\"horizontal\" | \"vertical\"",
+ default: "\"horizontal\"",
+ description: "Layout orientation — horizontal is 1280x720 (16:9), vertical is 720x1280 (9:16)",
+ },
+ {
+ name: "accentColor",
+ type: "string",
+ default: "\"#f5a623\"",
+ description: "Accent color used for the star icon and counter highlight",
+ },
+ {
+ name: "speed",
+ type: "number",
+ default: "1",
+ description: "Multiplier for the overall animation speed — higher values compress the fly-through",
+ },
+ {
+ name: "theme",
+ type: "\"light\" | \"dark\"",
+ default: "\"light\"",
+ description: "Color theme for the composition background and text",
+ },
+ ]}
+/>
+
+### Stargazer shape
+
+Each item in the `stargazers` array must conform to this shape:
+
+<PropsTable
+ rows={[
+ {
+ name: "login",
+ type: "string",
+ description: "GitHub username displayed in the list row",
+ },
+ {
+ name: "avatarUrl",
+ type: "string",
+ description: "Full URL to the user's GitHub avatar (must be CORS-accessible for MP4 export)",
+ },
+ {
+ name: "starredAt",
+ type: "string",
+ description: "ISO 8601 timestamp of when the user starred the repo (e.g. \"2021-03-15T10:00:00Z\")",
+ },
+ ]}
+/>
diff --git a/content/docs/social/index.mdx b/content/docs/social/index.mdx
new file mode 100644
index 00000000..06e9789c
--- /dev/null
+++ b/content/docs/social/index.mdx
@@ -0,0 +1,17 @@
+---
+title: Social
+description: Remotion compositions for sharing milestones and social proof
+---
+
+Ready-to-install compositions that turn GitHub stats, product launches, and community milestones into shareable video moments.
+
+<ComponentCardGrid
+ items={[
+ {
+ name: "GitHubStars",
+ description: "Stargazer fly-through with an odometer counter — paste a repo, preview the animation, download MP4",
+ status: "stable",
+ href: "/docs/social/github-stars",
+ },
+ ]}
+/>
diff --git a/content/docs/social/meta.json b/content/docs/social/meta.json
new file mode 100644
index 00000000..e62b3de2
--- /dev/null
+++ b/content/docs/social/meta.json
@@ -0,0 +1,5 @@
+{
+ "title": "Social",
+ "collapsible": false,
+ "pages": ["index", "github-stars"]
+}
diff --git a/registry.json b/registry.json
index a0fcd5c4..cc2c6807 100644
--- a/registry.json
+++ b/registry.json
@@ -898,6 +898,20 @@
"target": "components/remocn/visual-docs-snippet.tsx"
}
]
+ },
+ {
+ "name": "github-stars",
+ "type": "registry:component",
+ "title": "GitHub Stars",
+ "description": "Inertial fly-through of a repo's stargazers with a synced count-up odometer that locks on the total. Horizontal 16:9 or vertical 9:16.",
+ "dependencies": ["remotion", "date-fns"],
+ "files": [
+ {
+ "path": "registry/remocn/github-stars/index.tsx",
+ "type": "registry:component",
+ "target": "components/remocn/github-stars.tsx"
+ }
+ ]
}
]
}
diff --git a/registry/__index__.tsx b/registry/__index__.tsx
index 446ffe7d..b0f8ffa5 100644
--- a/registry/__index__.tsx
+++ b/registry/__index__.tsx
@@ -45,6 +45,8 @@ import { EcosystemConstellation } from "@/registry/remocn/ecosystem-constellatio
import { ecosystemConstellationConfig } from "@/registry/remocn/ecosystem-constellation/config";
import { FrostedGlassWipe } from "@/registry/remocn/frosted-glass-wipe";
import { frostedGlassWipeConfig } from "@/registry/remocn/frosted-glass-wipe/config";
+import { GitHubStars } from "@/registry/remocn/github-stars";
+import { githubStarsConfig } from "@/registry/remocn/github-stars/config";
import { GlassCodeBlock } from "@/registry/remocn/glass-code-block";
import { glassCodeBlockConfig } from "@/registry/remocn/glass-code-block/config";
import { GridPixelateWipe } from "@/registry/remocn/grid-pixelate-wipe";
@@ -341,6 +343,7 @@ const registry: Record<string, RegistryEntry> = {
Component: VisualDocsSnippet,
config: visualDocsSnippetConfig,
},
+ "github-stars": { Component: GitHubStars, config: githubStarsConfig },
};
// Append the shared controls (e.g. `speed`) to every component config so
@@ -349,4 +352,20 @@ for (const { config } of Object.values(registry)) {
config.controls = { ...config.controls, ...SHARED_CONTROLS };
}
+// github-stars must land its count-up exactly on the final frame. A speed < 1
+// would stop the shared progress driver short (the count never reaches the
+// total), so this component intentionally deviates from SHARED_CONTROLS and
+// caps `speed` at a minimum of 1. Reassigning the existing key keeps its order.
+const githubStars = registry["github-stars"];
+if (githubStars) {
+ githubStars.config.controls.speed = {
+ type: "number",
+ default: 1,
+ min: 1,
+ max: 4,
+ step: 0.25,
+ label: "Speed",
+ };
+}
+
export default registry;
diff --git a/registry/remocn/github-stars/__tests__/github-stars.test.ts b/registry/remocn/github-stars/__tests__/github-stars.test.ts
new file mode 100644
index 00000000..654cf56b
--- /dev/null
+++ b/registry/remocn/github-stars/__tests__/github-stars.test.ts
@@ -0,0 +1,335 @@
+/**
+ * Unit tests for pure helpers in registry/remocn/github-stars/index.tsx.
+ *
+ * Run with:
+ * bun add -d vitest
+ * bunx vitest run registry/remocn/github-stars/__tests__/github-stars.test.ts
+ *
+ * No React DOM or Remotion player needed — only pure JS logic is exercised.
+ * All tests are fully deterministic (no network, no Date.now).
+ */
+
+import { describe, expect, it } from "vitest";
+
+import {
+ SAMPLE_STARGAZERS,
+ computeCounterProgress,
+ computeScrollProgress,
+ computeSpacerRows,
+ downsampleStargazers,
+ getStarCount,
+ isScrollContained,
+ type Stargazer,
+} from "../index";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Build a synthetic stargazer array of length `n`. */
+function makeStargazers(n: number): Stargazer[] {
+ return Array.from({ length: n }, (_, i) => ({
+ login: `user${i}`,
+ avatarUrl: `https://avatars.githubusercontent.com/u/${i + 1}?v=4`,
+ starredAt: `2021-01-${String((i % 28) + 1).padStart(2, "0")}`,
+ }));
+}
+
+// ---------------------------------------------------------------------------
+// downsampleStargazers
+// ---------------------------------------------------------------------------
+
+describe("downsampleStargazers", () => {
+ it("reduces a large array to at most 60 entries", () => {
+ const input = makeStargazers(5000);
+ const result = downsampleStargazers(input);
+ expect(result.length).toBeLessThanOrEqual(60);
+ });
+
+ it("preserves the first entry from a large array", () => {
+ const input = makeStargazers(5000);
+ const result = downsampleStargazers(input);
+ expect(result[0]).toBe(input[0]);
+ });
+
+ it("preserves the last entry from a large array", () => {
+ const input = makeStargazers(5000);
+ const result = downsampleStargazers(input);
+ expect(result[result.length - 1]).toBe(input[input.length - 1]);
+ });
+
+ it("keeps entries in original order (no resorting)", () => {
+ const input = makeStargazers(5000);
+ const result = downsampleStargazers(input);
+ let prevIdx = -1;
+ for (const entry of result) {
+ const idx = input.indexOf(entry);
+ expect(idx).toBeGreaterThan(prevIdx);
+ prevIdx = idx;
+ }
+ });
+
+ it("returns the array unchanged when length < max (default 60)", () => {
+ const input = makeStargazers(12);
+ const result = downsampleStargazers(input);
+ expect(result).toBe(input); // same reference — no copy needed
+ });
+
+ it("returns the array unchanged when length === max", () => {
+ const input = makeStargazers(60);
+ const result = downsampleStargazers(input);
+ expect(result).toBe(input);
+ });
+
+ it("returns an empty array for empty input", () => {
+ expect(downsampleStargazers([])).toEqual([]);
+ });
+
+ it("returns a single-element array unchanged", () => {
+ const input = makeStargazers(1);
+ const result = downsampleStargazers(input);
+ expect(result).toHaveLength(1);
+ expect(result[0]).toBe(input[0]);
+ });
+
+ it("respects a custom max parameter", () => {
+ const input = makeStargazers(200);
+ const result = downsampleStargazers(input, 10);
+ expect(result.length).toBeLessThanOrEqual(10);
+ expect(result[0]).toBe(input[0]);
+ expect(result[result.length - 1]).toBe(input[input.length - 1]);
+ });
+
+ it("returns exactly 1 entry when max=1 with a large input", () => {
+ // Under a strict cap of 1 only the FIRST entry can be kept (there is no
+ // room to also preserve the last). first+last preservation applies at max>=2.
+ const input = makeStargazers(100);
+ const result = downsampleStargazers(input, 1);
+ expect(result).toHaveLength(1);
+ expect(result[0]).toBe(input[0]);
+ });
+});
+
+// ---------------------------------------------------------------------------
+// computeScrollProgress
+// ---------------------------------------------------------------------------
+
+const BASE = { speed: 1, durationInFrames: 300 } as const;
+
+// Mirror of the (unexported) SCROLL_OVERSHOOT bound in index.tsx so the elastic
+// peak can be asserted without leaking the constant into the public API.
+const SCROLL_OVERSHOOT = 1.0658;
+
+describe("computeCounterProgress", () => {
+ it("is 0 at frame 0", () => {
+ expect(computeCounterProgress({ frame: 0, ...BASE })).toBe(0);
+ });
+
+ it("returns exactly 1 at frame === durationInFrames", () => {
+ expect(
+ computeCounterProgress({ frame: BASE.durationInFrames, ...BASE }),
+ ).toBe(1);
+ });
+
+ it("returns exactly 1 for frames beyond durationInFrames", () => {
+ expect(
+ computeCounterProgress({ frame: BASE.durationInFrames + 100, ...BASE }),
+ ).toBe(1);
+ });
+
+ it("is monotonically non-decreasing across the full duration", () => {
+ let prev = -Infinity;
+ for (let f = 0; f <= BASE.durationInFrames; f++) {
+ const val = computeCounterProgress({ frame: f, ...BASE });
+ expect(val).toBeGreaterThanOrEqual(prev);
+ prev = val;
+ }
+ });
+
+ it("stays within [0, 1] for every frame in the duration", () => {
+ for (let f = 0; f <= BASE.durationInFrames + 10; f++) {
+ const val = computeCounterProgress({ frame: f, ...BASE });
+ expect(val).toBeGreaterThanOrEqual(0);
+ expect(val).toBeLessThanOrEqual(1);
+ }
+ });
+
+ it("speed=0.5 at frame 150 yields the same progress as speed=1 at frame 75", () => {
+ const slow = computeCounterProgress({
+ frame: 150,
+ speed: 0.5,
+ durationInFrames: 300,
+ });
+ const normal = computeCounterProgress({ frame: 75, ...BASE });
+ expect(slow).toBeCloseTo(normal, 6);
+ });
+});
+
+describe("computeScrollProgress", () => {
+ it("is 0 at frame 0", () => {
+ expect(computeScrollProgress({ frame: 0, ...BASE })).toBe(0);
+ });
+
+ it("returns exactly 1 at frame === durationInFrames", () => {
+ expect(
+ computeScrollProgress({ frame: BASE.durationInFrames, ...BASE }),
+ ).toBe(1);
+ });
+
+ it("returns exactly 1 for frames beyond durationInFrames (clamped)", () => {
+ expect(
+ computeScrollProgress({ frame: BASE.durationInFrames + 100, ...BASE }),
+ ).toBe(1);
+ });
+
+ it("stays within [0, SCROLL_OVERSHOOT] for every frame in the duration", () => {
+ for (let f = 0; f <= BASE.durationInFrames + 10; f++) {
+ const val = computeScrollProgress({ frame: f, ...BASE });
+ expect(val).toBeGreaterThanOrEqual(0);
+ expect(val).toBeLessThanOrEqual(SCROLL_OVERSHOOT);
+ }
+ });
+
+ it("returns to exactly 1 by the final frame", () => {
+ expect(
+ computeScrollProgress({ frame: BASE.durationInFrames, ...BASE }),
+ ).toBe(1);
+ });
+
+ it("speed=0.5 at frame 150 yields the same progress as speed=1 at frame 75", () => {
+ const slow = computeScrollProgress({
+ frame: 150,
+ speed: 0.5,
+ durationInFrames: 300,
+ });
+ const normal = computeScrollProgress({ frame: 75, ...BASE });
+ expect(slow).toBeCloseTo(normal, 6);
+ });
+});
+
+describe("maxScrollOvershoot / elastic peak", () => {
+ it("peaks at ≈1.0657 near t≈0.63 (frame≈189 at dur=300)", () => {
+ const dur = 300;
+ let max = -Infinity;
+ let maxFrame = -1;
+ for (let f = 0; f <= dur; f++) {
+ const val = computeScrollProgress({ frame: f, speed: 1, durationInFrames: dur });
+ if (val > max) {
+ max = val;
+ maxFrame = f;
+ }
+ }
+ expect(max).toBeCloseTo(1.0657, 3);
+ expect(maxFrame).toBeGreaterThanOrEqual(185);
+ expect(maxFrame).toBeLessThanOrEqual(193);
+ });
+});
+
+describe("isScrollContained", () => {
+ const GEO = { rowH: 88, viewportH: 600, visibleRows: 6 } as const;
+
+ it("is contained for N=12 and reserves 2 spacer rows", () => {
+ expect(isScrollContained({ N: 12, ...GEO })).toBe(true);
+ expect(computeSpacerRows({ N: 12, ...GEO })).toBe(2);
+ });
+
+ it("is contained for N=30 and reserves 3 spacer rows", () => {
+ expect(isScrollContained({ N: 30, ...GEO })).toBe(true);
+ expect(computeSpacerRows({ N: 30, ...GEO })).toBe(3);
+ });
+
+ it("is contained for N=60 and reserves 5 spacer rows", () => {
+ expect(isScrollContained({ N: 60, ...GEO })).toBe(true);
+ expect(computeSpacerRows({ N: 60, ...GEO })).toBe(5);
+ });
+
+ it("is contained for a tiny list (N=3) where D clamps to 0", () => {
+ expect(isScrollContained({ N: 3, ...GEO })).toBe(true);
+ });
+});
+
+// ---------------------------------------------------------------------------
+// getStarCount
+// ---------------------------------------------------------------------------
+
+describe("getStarCount", () => {
+ it("returns 0 when progress is 0", () => {
+ expect(getStarCount(0, 24813)).toBe(0);
+ });
+
+ it("returns totalStars when progress is 1", () => {
+ expect(getStarCount(1, 24813)).toBe(24813);
+ });
+
+ it("rounds to the nearest integer", () => {
+ // 0.5 * 3 = 1.5 → rounds to 2
+ expect(getStarCount(0.5, 3)).toBe(2);
+ // 0.4 * 5 = 2.0 → 2
+ expect(getStarCount(0.4, 5)).toBe(2);
+ // 0.1 * 3 = 0.3 → rounds to 0
+ expect(getStarCount(0.1, 3)).toBe(0);
+ });
+
+ it("returns 0 when totalStars is 0", () => {
+ expect(getStarCount(0.5, 0)).toBe(0);
+ expect(getStarCount(1, 0)).toBe(0);
+ });
+
+ it("is monotonically non-decreasing as progress increases for a fixed totalStars", () => {
+ const steps = 1000;
+ const total = 24813;
+ let prev = -1;
+ for (let i = 0; i <= steps; i++) {
+ const count = getStarCount(i / steps, total);
+ expect(count).toBeGreaterThanOrEqual(prev);
+ prev = count;
+ }
+ });
+
+ it("never exceeds totalStars", () => {
+ const total = 100;
+ for (let i = 0; i <= 100; i++) {
+ expect(getStarCount(i / 100, total)).toBeLessThanOrEqual(total);
+ }
+ });
+});
+
+// ---------------------------------------------------------------------------
+// SAMPLE_STARGAZERS
+// ---------------------------------------------------------------------------
+
+describe("SAMPLE_STARGAZERS", () => {
+ it("is non-empty", () => {
+ expect(SAMPLE_STARGAZERS.length).toBeGreaterThan(0);
+ });
+
+ it("each entry has login, avatarUrl, and starredAt fields", () => {
+ for (const sg of SAMPLE_STARGAZERS) {
+ expect(typeof sg.login).toBe("string");
+ expect(sg.login.length).toBeGreaterThan(0);
+ expect(typeof sg.avatarUrl).toBe("string");
+ expect(sg.avatarUrl.length).toBeGreaterThan(0);
+ expect(typeof sg.starredAt).toBe("string");
+ expect(sg.starredAt.length).toBeGreaterThan(0);
+ }
+ });
+
+ it("each starredAt is a valid ISO date string parseable by Date", () => {
+ for (const sg of SAMPLE_STARGAZERS) {
+ const d = new Date(sg.starredAt);
+ expect(Number.isNaN(d.getTime())).toBe(false);
+ }
+ });
+
+ it("avatarUrls are HTTPS GitHub avatar URLs", () => {
+ for (const sg of SAMPLE_STARGAZERS) {
+ expect(sg.avatarUrl).toMatch(/^https:\/\/avatars\.githubusercontent\.com\//);
+ }
+ });
+
+ it("logins are unique within the sample set", () => {
+ const logins = SAMPLE_STARGAZERS.map((sg) => sg.login);
+ const unique = new Set(logins);
+ expect(unique.size).toBe(logins.length);
+ });
+});
diff --git a/registry/remocn/github-stars/config.ts b/registry/remocn/github-stars/config.ts
new file mode 100644
index 00000000..a8a50255
--- /dev/null
+++ b/registry/remocn/github-stars/config.ts
@@ -0,0 +1,45 @@
+import {
+ type ComponentConfig,
+ FPS,
+ H,
+ W,
+} from "@/lib/customizer-config";
+
+export const githubStarsConfig: ComponentConfig = {
+ componentName: "GitHubStars",
+ importPath: "@/components/remocn/github-stars",
+ controls: {
+ repo: {
+ type: "text",
+ default: "kapishdima/remocn",
+ label: "Repository",
+ },
+ totalStars: {
+ type: "number",
+ default: 24813,
+ min: 0,
+ max: 500000,
+ step: 1,
+ label: "Total stars",
+ },
+ orientation: {
+ type: "select",
+ default: "horizontal",
+ options: ["horizontal", "vertical"],
+ label: "Orientation",
+ },
+ accentColor: { type: "color", default: "#f5a623", label: "Accent" },
+ theme: {
+ type: "select",
+ default: "light",
+ options: ["light", "dark"],
+ label: "Theme",
+ },
+ // `speed` is appended from SHARED_CONTROLS in registry/__index__.tsx.
+ // `stargazers` is an array → not a control; preview uses SAMPLE_STARGAZERS.
+ },
+ durationInFrames: 300,
+ fps: FPS,
+ compositionWidth: W,
+ compositionHeight: H,
+};
diff --git a/registry/remocn/github-stars/index.tsx b/registry/remocn/github-stars/index.tsx
new file mode 100644
index 00000000..c24fec3b
--- /dev/null
+++ b/registry/remocn/github-stars/index.tsx
@@ -0,0 +1,721 @@
+"use client";
+
+import { format, parseISO } from "date-fns";
+import type React from "react";
+import { useState } from "react";
+import {
+ AbsoluteFill,
+ Easing,
+ Img,
+ interpolate,
+ useCurrentFrame,
+ useVideoConfig,
+} from "remotion";
+
+export interface Stargazer {
+ login: string;
+ avatarUrl: string;
+ /** ISO date string, e.g. "2021-03-04" */
+ starredAt: string;
+}
+
+export interface GitHubStarsProps {
+ repo?: string;
+ totalStars?: number;
+ stargazers?: Stargazer[];
+ orientation?: "horizontal" | "vertical";
+ accentColor?: string;
+ speed?: number;
+ theme?: "light" | "dark";
+}
+
+/**
+ * Built-in mock stargazers so the composition renders immediately from defaults
+ * (own-your-code: no external data needed after `shadcn add`). Real low-id GitHub
+ * avatar URLs are CORS-ok, so the docs preview shows round photos.
+ */
+export const SAMPLE_STARGAZERS: Stargazer[] = [
+ { login: "mojombo", avatarUrl: "https://avatars.githubusercontent.com/u/1?v=4", starredAt: "2021-03-04" },
+ { login: "defunkt", avatarUrl: "https://avatars.githubusercontent.com/u/2?v=4", starredAt: "2021-06-12" },
+ { login: "pjhyett", avatarUrl: "https://avatars.githubusercontent.com/u/3?v=4", starredAt: "2021-09-21" },
+ { login: "wycats", avatarUrl: "https://avatars.githubusercontent.com/u/4?v=4", starredAt: "2021-12-08" },
+ { login: "ezmobius", avatarUrl: "https://avatars.githubusercontent.com/u/14?v=4", starredAt: "2022-03-17" },
+ { login: "ivey", avatarUrl: "https://avatars.githubusercontent.com/u/18?v=4", starredAt: "2022-06-29" },
+ { login: "evanphx", avatarUrl: "https://avatars.githubusercontent.com/u/25?v=4", starredAt: "2022-09-14" },
+ { login: "vanpelt", avatarUrl: "https://avatars.githubusercontent.com/u/26?v=4", starredAt: "2022-12-23" },
+ { login: "wayneeseguin", avatarUrl: "https://avatars.githubusercontent.com/u/28?v=4", starredAt: "2023-03-09" },
+ { login: "brynary", avatarUrl: "https://avatars.githubusercontent.com/u/30?v=4", starredAt: "2023-07-19" },
+ { login: "kevinclark", avatarUrl: "https://avatars.githubusercontent.com/u/31?v=4", starredAt: "2023-11-02" },
+ { login: "technoweenie", avatarUrl: "https://avatars.githubusercontent.com/u/21?v=4", starredAt: "2024-02-15" },
+];
+
+const FONT_FAMILY =
+ "var(--font-geist-sans), -apple-system, BlinkMacSystemFont, sans-serif";
+
+interface Theme {
+ bg: string;
+ bgSubtle: string;
+ fg: string;
+ fgMuted: string;
+ border: string;
+}
+
+const THEMES: Record<"light" | "dark", Theme> = {
+ light: {
+ bg: "#ffffff",
+ bgSubtle: "#fafafa",
+ fg: "#171717",
+ fgMuted: "#737373",
+ border: "#ededed",
+ },
+ dark: {
+ bg: "#0a0a0a",
+ bgSubtle: "#111113",
+ fg: "#fafafa",
+ fgMuted: "#a1a1aa",
+ border: "#262626",
+ },
+};
+
+// --- Pure helpers (unit-tested) -------------------------------------------
+
+/**
+ * Clamp a stargazer list to at most `max` evenly-sampled keyframe rows while
+ * always preserving the first and last entry. Safety net for callers that pass
+ * a huge array straight into the composition.
+ */
+export function downsampleStargazers(
+ stargazers: Stargazer[],
+ max = 60,
+): Stargazer[] {
+ const len = stargazers.length;
+ if (len <= max) return stargazers;
+ if (max <= 1) return len ? [stargazers[0]] : [];
+ const out: Stargazer[] = [];
+ for (let i = 0; i < max; i++) {
+ out.push(stargazers[Math.round((i * (len - 1)) / (max - 1))]);
+ }
+ return out;
+}
+
+const MAX_ELASTIC_OVERSHOOT = 0.0658; // Easing.elastic(1) peak−1 (true ≈0.0657267), rounded UP for use as a safety bound
+const SCROLL_OVERSHOOT = 1 + MAX_ELASTIC_OVERSHOOT; // ≈1.0658
+const MASK_SOLID_FRACTION = 0.88; // bottom fade mask is solid until 88% of viewport height
+
+/** Monotonic counter ramp — mirrors the reference StarCount easing. Drives the
+ * odometer, which must stay monotonic or the digit wheels roll backward. */
+export function computeCounterProgress({
+ frame,
+ speed = 1,
+ durationInFrames,
+}: {
+ frame: number;
+ speed?: number;
+ durationInFrames: number;
+}): number {
+ return interpolate(frame * speed, [0, durationInFrames], [0, 1], {
+ extrapolateLeft: "clamp",
+ extrapolateRight: "clamp",
+ easing: Easing.bezier(0.5, 1, 0.5, 1),
+ });
+}
+
+/** Elastic scroll ramp — mirrors the reference avatar slide. NON-monotonic:
+ * overshoots to ~SCROLL_OVERSHOOT near t≈0.63 and settles to exactly 1 at t=1.
+ * Drives only scrollY (never the odometer). */
+export function computeScrollProgress({
+ frame,
+ speed = 1,
+ durationInFrames,
+}: {
+ frame: number;
+ speed?: number;
+ durationInFrames: number;
+}): number {
+ return interpolate(frame * speed, [0, durationInFrames], [0, 1], {
+ extrapolateLeft: "clamp",
+ extrapolateRight: "clamp",
+ easing: Easing.elastic(1),
+ });
+}
+
+/** Empty rows appended below the last stargazer so the elastic recoil never
+ * lifts real content off the mask-solid zone, revealing a void. Single source
+ * of truth shared with isScrollContained so the two cannot drift. */
+export function computeSpacerRows({
+ N,
+ rowH,
+ viewportH,
+ visibleRows,
+}: {
+ N: number;
+ rowH: number;
+ viewportH: number;
+ visibleRows: number;
+}): number {
+ const D = Math.max(0, (N - visibleRows + 1) * rowH);
+ const needPx = MASK_SOLID_FRACTION * viewportH - N * rowH + SCROLL_OVERSHOOT * D;
+ return Math.max(0, Math.ceil(needPx / rowH));
+}
+
+/** True when, at the elastic overshoot peak, content still fills the mask-solid
+ * zone (no void revealed). True by construction given computeSpacerRows. */
+export function isScrollContained({
+ N,
+ rowH,
+ viewportH,
+ visibleRows,
+}: {
+ N: number;
+ rowH: number;
+ viewportH: number;
+ visibleRows: number;
+}): boolean {
+ const D = Math.max(0, (N - visibleRows + 1) * rowH);
+ const spacerPx = computeSpacerRows({ N, rowH, viewportH, visibleRows }) * rowH;
+ return N * rowH + spacerPx - SCROLL_OVERSHOOT * D >= MASK_SOLID_FRACTION * viewportH;
+}
+
+/** The running counter value for a given scroll progress. Locks at totalStars. */
+export function getStarCount(scrollProgress: number, totalStars: number): number {
+ return Math.round(scrollProgress * totalStars);
+}
+
+// --- Sub-components --------------------------------------------------------
+
+function StarGlyph({ size, fill }: { size: number; fill: string }) {
+ return (
+ <svg
+ width={size}
+ height={size}
+ viewBox="0 0 24 24"
+ fill={fill}
+ aria-hidden="true"
+ >
+ <path d="M12 2.5l2.92 5.92 6.53.95-4.72 4.6 1.11 6.5L12 17.9l-5.85 3.07 1.12-6.5L2.55 9.87l6.53-.95L12 2.5z" />
+ </svg>
+ );
+}
+
+function Avatar({
+ login,
+ avatarUrl,
+ size,
+ theme,
+}: {
+ login: string;
+ avatarUrl: string;
+ size: number;
+ theme: Theme;
+}) {
+ const [errored, setErrored] = useState(false);
+ const ringStyle = {
+ width: size,
+ height: size,
+ borderRadius: 9999,
+ border: `1px solid ${theme.border}`,
+ flexShrink: 0,
+ } as const;
+
+ if (errored || !avatarUrl) {
+ return (
+ <div
+ style={{
+ ...ringStyle,
+ background: theme.bgSubtle,
+ display: "flex",
+ alignItems: "center",
+ justifyContent: "center",
+ color: theme.fgMuted,
+ fontSize: size * 0.42,
+ fontWeight: 600,
+ }}
+ >
+ {login.charAt(0).toUpperCase()}
+ </div>
+ );
+ }
+
+ return (
+ <Img
+ src={avatarUrl}
+ crossOrigin="anonymous"
+ onError={() => setErrored(true)}
+ style={{ ...ringStyle, objectFit: "cover" }}
+ />
+ );
+}
+
+function DigitColumn({
+ value,
+ fontSize,
+}: {
+ /** continuous wheel value in [0, 10) */
+ value: number;
+ fontSize: number;
+}) {
+ const cellHeight = fontSize * 1.1;
+ return (
+ <span
+ style={{
+ display: "inline-block",
+ overflow: "hidden",
+ height: cellHeight,
+ width: "0.62em",
+ verticalAlign: "top",
+ textAlign: "center",
+ }}
+ >
+ <span
+ style={{
+ display: "flex",
+ flexDirection: "column",
+ transform: `translateY(${-value * cellHeight}px)`,
+ }}
+ >
+ {[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 0].map((d, i) => (
+ <span key={i} style={{ height: cellHeight, lineHeight: `${cellHeight}px` }}>
+ {d}
+ </span>
+ ))}
+ </span>
+ </span>
+ );
+}
+
+function Odometer({
+ current,
+ fontSize,
+ color,
+ mutedColor,
+}: {
+ /** continuous running total (float) */
+ current: number;
+ fontSize: number;
+ color: string;
+ mutedColor: string;
+}) {
+ const intVal = Math.max(0, Math.round(current));
+ const formatted = intVal.toLocaleString("en-US");
+
+ // Walk right→left so each digit knows its decimal place; drive each wheel
+ // continuously from `current` (higher places roll slower → mechanical feel).
+ const cells: React.ReactNode[] = [];
+ let place = 0;
+ for (let i = formatted.length - 1; i >= 0; i--) {
+ const ch = formatted[i];
+ if (ch === ",") {
+ cells.unshift(
+ <span
+ key={`c${i}`}
+ style={{
+ display: "inline-block",
+ width: "0.32em",
+ color: mutedColor,
+ fontSize: "0.85em",
+ textAlign: "center",
+ }}
+ >
+ ,
+ </span>,
+ );
+ } else {
+ const wheel = (current / 10 ** place) % 10;
+ cells.unshift(
+ <DigitColumn key={`d${i}`} value={wheel < 0 ? 0 : wheel} fontSize={fontSize} />,
+ );
+ place++;
+ }
+ }
+
+ return (
+ <div
+ style={{
+ display: "flex",
+ alignItems: "baseline",
+ fontSize,
+ fontWeight: 800,
+ color,
+ fontFamily: FONT_FAMILY,
+ fontVariantNumeric: "tabular-nums",
+ letterSpacing: "-0.03em",
+ lineHeight: 1,
+ }}
+ >
+ {cells}
+ </div>
+ );
+}
+
+interface RowProps {
+ stargazer: Stargazer;
+ index: number;
+ rowH: number;
+ avatarSize: number;
+ loginSize: number;
+ dateFormat: string;
+ accent: string;
+ theme: Theme;
+ isActive: boolean;
+ settle: number;
+ showSeparator: boolean;
+ opacity: number;
+}
+
+function Row({
+ stargazer,
+ index,
+ rowH,
+ avatarSize,
+ loginSize,
+ dateFormat,
+ accent,
+ theme,
+ isActive,
+ settle,
+ showSeparator,
+ opacity,
+}: RowProps) {
+ let dateLabel = stargazer.starredAt;
+ try {
+ dateLabel = format(parseISO(stargazer.starredAt), dateFormat);
+ } catch {
+ // leave the raw string if it isn't a valid ISO date
+ }
+
+ return (
+ <div
+ style={{
+ position: "relative",
+ height: rowH,
+ display: "flex",
+ alignItems: "center",
+ paddingLeft: 24,
+ paddingRight: 24,
+ background: "transparent",
+ opacity,
+ boxSizing: "border-box",
+ borderBottom:
+ showSeparator && !isActive ? `1px solid ${theme.border}` : "none",
+ }}
+ >
+ {isActive && (
+ <>
+ <div
+ style={{
+ position: "absolute",
+ inset: 0,
+ background: theme.bgSubtle,
+ opacity: settle,
+ }}
+ />
+ <div
+ style={{
+ position: "absolute",
+ left: 0,
+ top: 0,
+ bottom: 0,
+ width: 2,
+ background: accent,
+ opacity: settle,
+ }}
+ />
+ </>
+ )}
+ <div style={{ position: "relative", display: "flex", alignItems: "center", width: "100%" }}>
+ <Avatar
+ login={stargazer.login}
+ avatarUrl={stargazer.avatarUrl}
+ size={avatarSize}
+ theme={theme}
+ />
+ <div style={{ marginLeft: 20, minWidth: 0, flex: 1 }}>
+ <div
+ style={{
+ fontSize: loginSize,
+ fontWeight: 600,
+ color: theme.fg,
+ fontFamily: FONT_FAMILY,
+ whiteSpace: "nowrap",
+ overflow: "hidden",
+ textOverflow: "ellipsis",
+ lineHeight: 1.2,
+ }}
+ >
+ {stargazer.login}
+ </div>
+ <div
+ style={{
+ fontSize: 18,
+ fontWeight: 400,
+ color: theme.fgMuted,
+ fontFamily: FONT_FAMILY,
+ lineHeight: 1.3,
+ }}
+ >
+ {dateLabel}
+ </div>
+ </div>
+ <div
+ style={{
+ display: "flex",
+ alignItems: "center",
+ gap: 8,
+ color: theme.fgMuted,
+ fontFamily: FONT_FAMILY,
+ fontSize: 18,
+ fontVariantNumeric: "tabular-nums",
+ flexShrink: 0,
+ }}
+ >
+ <StarGlyph size={20} fill={accent} />
+ <span>#{index + 1}</span>
+ </div>
+ </div>
+ </div>
+ );
+}
+
+// --- Main composition ------------------------------------------------------
+
+export function GitHubStars({
+ repo = "remotion-dev/remotion",
+ totalStars = 24813,
+ stargazers = SAMPLE_STARGAZERS,
+ orientation = "horizontal",
+ accentColor = "#f5a623",
+ speed = 1,
+ theme = "light",
+}: GitHubStarsProps) {
+ const frame = useCurrentFrame();
+ const { durationInFrames, width, height } = useVideoConfig();
+ const t = THEMES[theme] ?? THEMES.light;
+ const isVertical = orientation === "vertical";
+
+ // Render at the native reference size for the orientation, then scale to fit
+ // the actual canvas — keeps proportions at any resolution and letterboxes a
+ // vertical layout cleanly inside a horizontal preview canvas.
+ const refW = isVertical ? 720 : 1280;
+ const refH = isVertical ? 1280 : 720;
+ const stageScale = Math.min(width / refW, height / refH);
+
+ const rows = downsampleStargazers(stargazers);
+ const N = rows.length;
+
+ // Progress drivers: monotonic counter ramp + non-monotonic elastic scroll.
+ const counterProgress = computeCounterProgress({ frame, speed, durationInFrames });
+ const pScroll = computeScrollProgress({ frame, speed, durationInFrames });
+ const p = Math.max(0, Math.min(1, (frame * speed) / durationInFrames));
+
+ const current = counterProgress * totalStars;
+
+ // List viewport geometry (in reference px).
+ const rowH = isVertical ? 96 : 88;
+ const avatarSize = isVertical ? 60 : 56;
+ const loginSize = isVertical ? 30 : 28;
+ const dateFormat = isVertical ? "MMM yyyy" : "MMM d, yyyy";
+
+ const viewport = isVertical
+ ? { x: 48, y: 320, w: 624, h: 888, radius: 28 }
+ : { x: 560, y: 60, w: 640, h: 600, radius: 24 };
+
+ const visibleRows = Math.floor(viewport.h / rowH);
+ const D = Math.max(0, (N - visibleRows + 1) * rowH);
+ const scrollY = -pScroll * D;
+
+ // Empty spacer below the last row so the elastic overshoot never reveals a
+ // void inside the mask-solid zone. See computeSpacerRows.
+ const spacerRows = computeSpacerRows({ N, rowH, viewportH: viewport.h, visibleRows });
+ const spacerPx = spacerRows * rowH;
+
+ // Drive the active-row highlight off the SAME shared progress value as the
+ // scroll/odometer (p = clamp(frame*speed / dur)) so it can never desync. The
+ // `speed` control is capped at min 1 (registry/__index__.tsx) so p — and thus
+ // pScroll/the count — always reaches exactly 1 by the final frame.
+ const settle = interpolate(p, [0.92, 1], [0, 1], {
+ extrapolateLeft: "clamp",
+ extrapolateRight: "clamp",
+ });
+
+ // Counter zone type scale.
+ const counterSize = isVertical ? 96 : 120;
+ const starSize = isVertical ? 56 : 64;
+ const underlineMax = isVertical ? 200 : 240;
+ const underlineWidth = counterProgress * underlineMax;
+
+ const fadeMask =
+ "linear-gradient(to bottom, transparent 0, black 12%, black 88%, transparent 100%)";
+
+ const listViewport = (
+ <div
+ style={{
+ position: "absolute",
+ left: viewport.x,
+ top: viewport.y,
+ width: viewport.w,
+ height: viewport.h,
+ overflow: "hidden",
+ borderRadius: viewport.radius,
+ border: `1px solid ${t.border}`,
+ background: t.bg,
+ WebkitMaskImage: fadeMask,
+ maskImage: fadeMask,
+ }}
+ >
+ <div
+ style={{
+ transform: `translateY(${scrollY}px)`,
+ willChange: "transform",
+ }}
+ >
+ {rows.map((sg, i) => (
+ <Row
+ key={`${sg.login}-${i}`}
+ stargazer={sg}
+ index={i}
+ rowH={rowH}
+ avatarSize={avatarSize}
+ loginSize={loginSize}
+ dateFormat={dateFormat}
+ accent={accentColor}
+ theme={t}
+ isActive={i === N - 1}
+ settle={settle}
+ showSeparator={i < N - 1}
+ opacity={1}
+ />
+ ))}
+ {spacerPx > 0 && <div style={{ height: spacerPx }} aria-hidden="true" />}
+ </div>
+ </div>
+ );
+
+ const underline = (
+ <div
+ style={{
+ height: 4,
+ width: underlineWidth,
+ background: accentColor,
+ borderRadius: 2,
+ }}
+ />
+ );
+
+ const repoSlug = (
+ <div
+ style={{
+ fontSize: isVertical ? 20 : 24,
+ fontWeight: 500,
+ color: t.fgMuted,
+ fontFamily: FONT_FAMILY,
+ maxWidth: isVertical ? 600 : 392,
+ overflow: "hidden",
+ textOverflow: "ellipsis",
+ whiteSpace: "nowrap",
+ }}
+ >
+ {repo}
+ </div>
+ );
+
+ const counterZone = isVertical ? (
+ <div
+ style={{
+ position: "absolute",
+ left: 0,
+ top: 0,
+ width: refW,
+ height: 300,
+ paddingTop: 72,
+ display: "flex",
+ flexDirection: "column",
+ alignItems: "center",
+ gap: 14,
+ }}
+ >
+ <div style={{ display: "flex", alignItems: "center", gap: 20 }}>
+ <StarGlyph size={starSize} fill={accentColor} />
+ <Odometer
+ current={current}
+ fontSize={counterSize}
+ color={t.fg}
+ mutedColor={t.fgMuted}
+ />
+ </div>
+ {underline}
+ <div
+ style={{
+ display: "flex",
+ gap: 10,
+ fontSize: 20,
+ fontWeight: 500,
+ color: t.fgMuted,
+ fontFamily: FONT_FAMILY,
+ letterSpacing: "0.04em",
+ }}
+ >
+ <span style={{ letterSpacing: "0.12em" }}>STARGAZERS</span>
+ <span>·</span>
+ <span>{repo}</span>
+ </div>
+ </div>
+ ) : (
+ <div
+ style={{
+ position: "absolute",
+ left: 80,
+ top: 0,
+ width: 392,
+ height: refH,
+ display: "flex",
+ flexDirection: "column",
+ justifyContent: "center",
+ alignItems: "flex-start",
+ }}
+ >
+ <StarGlyph size={starSize} fill={accentColor} />
+ <div style={{ height: 20 }} />
+ <Odometer
+ current={current}
+ fontSize={counterSize}
+ color={t.fg}
+ mutedColor={t.fgMuted}
+ />
+ <div style={{ height: 16 }} />
+ {underline}
+ <div style={{ height: 20 }} />
+ <div
+ style={{
+ fontSize: 22,
+ fontWeight: 600,
+ letterSpacing: "0.18em",
+ textTransform: "uppercase",
+ color: t.fgMuted,
+ fontFamily: FONT_FAMILY,
+ }}
+ >
+ Stargazers
+ </div>
+ <div style={{ height: 28 }} />
+ {repoSlug}
+ </div>
+ );
+
+ return (
+ <AbsoluteFill style={{ background: t.bg }}>
+ <div
+ style={{
+ position: "absolute",
+ left: "50%",
+ top: "50%",
+ width: refW,
+ height: refH,
+ transform: `translate(-50%, -50%) scale(${stageScale})`,
+ }}
+ >
+ {counterZone}
+ {listViewport}
+ </div>
+ </AbsoluteFill>
+ );
+}