# GitHub Stars
URL: https://remocn.dev/docs/social/github-stars

Stargazer list fly-through with a synced odometer counter — renders standalone from sample data or accepts live stargazer props

- Install: `npx shadcn@latest add @remocn/github-stars`
- Vibe: data
- Natural length: 120f @ 30fps

> **Live generator**
>
> Want to see it with your own repo before installing? Head to [/stars](/stars), paste any GitHub repo URL, preview the animation, and download an MP4 — it's the live demo of this component.

## Installation

```bash
npx shadcn@latest add @remocn/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={120}
    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={120}
    fps={30}
    width={1280}
    height={720}
  />
);
```

## Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `repo` | `string` | `"remotion-dev/remotion"` | Repository shown in the heading (owner/name format) |
| `totalStars` | `number` | `24813` | Total star count the odometer counts up to |
| `stargazers` | `Stargazer[]` | `SAMPLE_STARGAZERS` | Array of stargazer objects that populate the fly-through list. Falls back to built-in sample data when omitted. |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Layout orientation — horizontal is 1280x720 (16:9), vertical is 720x1280 (9:16) |
| `accentColor` | `string` | `"#f5a623"` | Accent color used for the star icon and counter highlight |
| `speed` | `number` | `1` | Multiplier for the overall animation speed — higher values compress the fly-through |
| `theme` | `"light" \| "dark"` | `"light"` | Color theme for the composition background and text |

### Stargazer shape

Each item in the `stargazers` array must conform to this shape:

| Prop | Type | Default | Description |
|---|---|---|---|
| `login` | `string` | — | GitHub username displayed in the list row |
| `avatarUrl` | `string` | — | Full URL to the user's GitHub avatar (must be CORS-accessible for MP4 export) |
| `starredAt` | `string` | — | ISO 8601 timestamp of when the user starred the repo (e.g. "2021-03-15T10:00:00Z") |

## Use when
- Celebrating an OSS milestone — the count-up odometer landing on a star total is the payoff beat.
- A repo-showcase or social-proof scene needs real stargazer faces flying past.
- You want one self-contained card that pairs the avatar fly-through with the synced counter.

## Don't use when
- You only need the number to roll up without the stargazer fly-through — use `number-wheel` or `rolling-number`.
- The metric isn't GitHub stars — use a generic counter (`rolling-number`) or `animated-bar-chart` for compared values.
- You're depicting follower growth on X — use `x-followers-overview`.