"use client"; import { useEffect, useState, type ComponentProps, type CSSProperties, type ReactNode, } from "react"; import { ArrowUpRight, Star } from "lucide-react"; import { Counter, type CounterEffect } from "@/components/lazy-ui/counter"; import { cn } from "@/lib/utils"; export type GithubStarsVariant = | "default" | "star" | "ghost" | "solid" | "silver"; export type GithubStarsDisplayFormat = "full" | "compact" | "plus"; export type GithubStarsHoverMode = "none" | "label" | "full"; export interface GithubStarsButtonProps extends Omit, "children" | "href"> { /** GitHub username or organization. */ username: string; /** GitHub repository name. */ repo: string; /** Button label. @default "GitHub" */ label?: string; /** Controlled star value. Disables auto-fetch when provided. */ value?: number; /** Fallback star value before the API request resolves. @default 0 */ initialValue?: number; /** Fetch the repo star count automatically when `value` is not provided. */ fetchStars?: boolean; /** Optional proxy endpoint. Receives `owner` and `repo` query params. */ apiEndpoint?: string; /** Show the animated star count. @default true */ showCount?: boolean; /** Counter animation effect. @default "3d" */ counterEffect?: CounterEffect; /** Visual palette. @default "default" */ variant?: GithubStarsVariant; /** Number format for the star count. @default "compact" */ displayFormat?: GithubStarsDisplayFormat; /** Hover behavior. @default "none" */ hoverMode?: GithubStarsHoverMode; /** Label shown on hover when `hoverMode="label"`. @default "Star this" */ hoverLabel?: string; /** Inner text shown on hover when `hoverMode="full"`. @default "Star on GitHub" */ hoverContent?: ReactNode; /** * Duration in ms of the hover content swap (`label` / `full` modes). * @default 300 */ hoverDuration?: number; /** Override the computed repository href. */ href?: string; } type StarsResponse = { stars?: unknown; stargazers_count?: unknown; }; const VARIANT_CLASSES: Record = { default: "border-neutral-200 bg-white text-neutral-950 hover:border-neutral-300 hover:bg-neutral-50 " + "dark:border-white/10 dark:bg-white/[0.045] dark:text-white dark:hover:border-white/25 dark:hover:bg-white/[0.075]", star: "border-yellow-300/50 bg-yellow-50 text-yellow-900 hover:border-yellow-400/70 hover:bg-yellow-100 " + "dark:border-yellow-400/25 dark:bg-yellow-400/10 dark:text-yellow-50 dark:hover:border-yellow-400/50 dark:hover:bg-yellow-400/15", ghost: "border-transparent bg-transparent text-neutral-700 hover:border-neutral-200 hover:bg-neutral-50 " + "dark:border-white/[0.05] dark:bg-transparent dark:text-neutral-200 dark:hover:border-white/15 dark:hover:bg-white/[0.04]", solid: "border-neutral-900 bg-neutral-950 text-white hover:border-neutral-800 hover:bg-black " + "dark:border-white/15 dark:bg-black dark:hover:border-white/30 dark:hover:bg-neutral-950", silver: "border-white/30 bg-[linear-gradient(180deg,#fff,#d4d4d4,#8a8a8a)] text-black hover:border-white/55 hover:bg-[linear-gradient(180deg,#fff,#e5e5e5,#a3a3a3)]", }; const SHIMMER_CLASSES: Record = { default: "bg-[linear-gradient(110deg,transparent_0%,rgba(255,255,255,0.7)_48%,transparent_68%)] dark:bg-[linear-gradient(110deg,transparent_0%,rgba(255,255,255,0.18)_48%,transparent_68%)]", star: "bg-[linear-gradient(110deg,transparent_0%,rgba(255,255,255,0.7)_48%,transparent_68%)] dark:bg-[linear-gradient(110deg,transparent_0%,rgba(255,225,120,0.28)_48%,transparent_68%)]", ghost: "bg-[linear-gradient(110deg,transparent_0%,rgba(255,255,255,0.5)_48%,transparent_68%)] dark:bg-[linear-gradient(110deg,transparent_0%,rgba(255,255,255,0.12)_48%,transparent_68%)]", solid: "bg-[linear-gradient(110deg,transparent_0%,rgba(255,255,255,0.25)_48%,transparent_68%)]", silver: "bg-[linear-gradient(110deg,transparent_0%,rgba(255,255,255,0.85)_48%,transparent_68%)]", }; const DIVIDER_CLASSES: Record = { default: "bg-neutral-200 group-hover:bg-neutral-300 dark:bg-white/10 dark:group-hover:bg-white/20", star: "bg-yellow-300/50 group-hover:bg-yellow-400/70 dark:bg-yellow-400/20 dark:group-hover:bg-yellow-400/35", ghost: "bg-neutral-200 group-hover:bg-neutral-300 dark:bg-white/10 dark:group-hover:bg-white/20", solid: "bg-white/15 group-hover:bg-white/30", silver: "bg-black/15 group-hover:bg-black/30", }; const COUNT_CLASSES: Record = { default: "text-neutral-600 group-hover:text-neutral-900 dark:text-neutral-400 dark:group-hover:text-white", star: "text-yellow-700 group-hover:text-yellow-950 dark:text-yellow-100/70 dark:group-hover:text-yellow-50", ghost: "text-neutral-500 group-hover:text-neutral-800 dark:text-neutral-400 dark:group-hover:text-white", solid: "text-neutral-400 group-hover:text-white", silver: "text-neutral-700 group-hover:text-black", }; const STAR_CLASSES: Record = { default: "fill-yellow-400 text-yellow-400", star: "fill-yellow-400 text-yellow-400", ghost: "fill-yellow-400 text-yellow-400", solid: "fill-yellow-400 text-yellow-400", silver: "fill-yellow-500 text-yellow-500", }; function formatStars(value: number, format: GithubStarsDisplayFormat) { const v = Math.max(0, Math.round(value)); if (format === "full") return v.toLocaleString("en-US"); if (format === "plus") return formatPlus(v); return formatCompact(v); } function formatCompact(v: number) { if (v < 1000) return String(v); return `${(v / 1000).toFixed(1).replace(/\.0$/, "")}k`; } function formatPlus(v: number) { if (v < 10) return String(v); // Round down keeping 2 leading significant digits, then append "+". const order = Math.pow(10, Math.floor(Math.log10(v)) - 1); return `${Math.floor(v / order) * order}+`; } function githubRepoHref(username: string, repo: string) { return `https://github.com/${username}/${repo}`; } function starsUrl(username: string, repo: string, apiEndpoint?: string) { if (!apiEndpoint) { return `https://api.github.com/repos/${encodeURIComponent(username)}/${encodeURIComponent(repo)}`; } const params = new URLSearchParams({ owner: username, repo }); const separator = apiEndpoint.includes("?") ? "&" : "?"; return `${apiEndpoint}${separator}${params.toString()}`; } function readStarCount(data: StarsResponse) { const value = data.stars ?? data.stargazers_count; return typeof value === "number" && Number.isFinite(value) ? value : undefined; } export function GithubStarsButton({ username, repo, label = "GitHub", value, initialValue = 0, fetchStars, apiEndpoint, showCount = true, counterEffect = "3d", variant = "default", displayFormat = "compact", hoverMode = "none", hoverLabel = "Star this", hoverContent = "Star on GitHub", hoverDuration = 300, href, className, style, target = "_blank", rel, "aria-label": ariaLabel, ...props }: GithubStarsButtonProps) { const shouldFetch = (fetchStars ?? value === undefined) && value === undefined; const [fetchedStars, setFetchedStars] = useState(initialValue); const [failed, setFailed] = useState(false); // Reset fetched state when the target repo changes (instead of doing it // inside the effect, which lints as a cascading-render bug). This is the // React-recommended pattern for resetting state on prop change. const repoKey = `${username}/${repo}`; const [prevRepoKey, setPrevRepoKey] = useState(repoKey); if (prevRepoKey !== repoKey) { setPrevRepoKey(repoKey); setFetchedStars(initialValue); setFailed(false); } const displayValue = value ?? (shouldFetch ? fetchedStars : initialValue); const repoHref = href ?? githubRepoHref(username, repo); useEffect(() => { if (!shouldFetch) return; const controller = new AbortController(); let active = true; async function loadStars() { try { const response = await fetch(starsUrl(username, repo, apiEndpoint), { signal: controller.signal, }); if (!response.ok) throw new Error("Unable to load GitHub stars"); const data = (await response.json()) as StarsResponse; const next = readStarCount(data); if (active && next !== undefined) { setFetchedStars(next); setFailed(false); } } catch { if (active && !controller.signal.aborted) setFailed(true); } } void loadStars(); return () => { active = false; controller.abort(); }; }, [apiEndpoint, repo, shouldFetch, username]); const formatFn = (n: number) => formatStars(n, displayFormat); const rootStyle: CSSProperties = { ["--hover-dur" as string]: `${Math.max(0, hoverDuration)}ms`, ...style, }; return ( {/* Default content. In hoverMode='full' it fades out so the overlay can take over. Duration comes from --hover-dur (the `hoverDuration` prop) so the consumer can fine-tune feel. */} {hoverMode === "label" ? ( {label} {hoverLabel} ) : ( {label} )} {showCount && ( <> )} {/* Star + soft halo. The halo blooms behind on hover. */} {/* Hover overlay — cross-fades with the default content above. */} {hoverMode === "full" && ( )} {/* Sparkle particles — staggered pop around the star on hover. */} ); } function GithubMark() { return ( ); } GithubStarsButton.displayName = "GithubStarsButton";

GitHub Stars Button

Customize

Usage