🌍 GitHub Visitor Counter

Display visitor country flags on your GitHub profile

An elegant and highly customizable visitor counter that displays country flags of your GitHub profile visitors.
Track and showcase your global audience with four display modes, multiple themes, flexible layouts, and real-time configuration.
One-click FREE deployment with zero maintenance required. Built with Next.js 15, React 19, and TypeScript.

🚀 Live Demo · 📖 Documentation · 🎨 Configuration Tool · 🐛 Issues

Share GitHub Visitor Counter

^{🌟 Pioneering GitHub profile enhancement. Built for developers worldwide.}

📸 Live Examples

[!TIP] Click on any example to see it in action and customize it for your profile!

GitHub Dark Theme - 4 columns with 12 flags

Default Theme (left) and Dark Theme (right)

🎨 More Theme Examples

GitHub Theme

Transparent Theme

With Country Labels

🚀 Quick Start

No registration, no configuration, no hassle. Add this single line to your GitHub profile README:

![](https://github-visitor-counter-tau.vercel.app/api?username=YOUR_USERNAME)

Replace YOUR_USERNAME with your actual GitHub username. That's it! 🎉

[!TIP] Compared to official Flag Counter:

• ✅ No account creation or email verification
• ✅ No waiting for approval
• ✅ Works instantly - just paste and go
• ✅ One line of markdown vs complex HTML code

Tech Stack Badges:

We are passionate developers creating next-generation GitHub profile enhancement tools. By adopting modern serverless architecture and cutting-edge web technologies, we provide developers with powerful, scalable, and user-friendly solutions to showcase their global reach.

Whether you're a solo developer or part of a large team, this visitor counter will help you visualize your international audience with style and precision. Choose from four distinct display modes to match your profile's aesthetic, and customize every aspect with our interactive dashboard. The project is actively maintained and continuously improved based on community feedback.

Compared to official Flag Counter, our solution offers:

🎯 Best of Both Worlds: Our solution is fully compatible with official Flag Counter IDs. Use our streamlined interface for quick setup, or integrate your existing Counter ID to access the official analytics dashboard!

	No installation required! Visit our live demo to customize your counter instantly.
	Star us on GitHub! Get notifications for new themes and features.

⭐ Star History

Experience our interactive configuration tool that provides instant preview of your visitor counter. Our innovative web interface allows you to customize every aspect of your counter with real-time visual feedback.

Interactive Configuration Tool - Try it live!

Key capabilities include:

• 🎨 Live Preview: See changes instantly as you customize
• 📋 Copy-Ready Code: Generated markdown code ready to use
• 🎯 Smart Defaults: Optimized settings for best appearance
• 🔄 Real-time Updates: No refresh needed for parameter changes

Choose from carefully crafted themes or create your own with custom colors. Our theme system supports both light and dark modes with GitHub-native styling options.

Default Theme (left) and GitHub Dark Theme (right)

Available Themes:

• Default: Clean white background with subtle borders
• Dark: Modern dark theme perfect for dark-mode profiles
• GitHub: Native GitHub styling integration
• GitHub Dark: GitHub's dark theme variant
• Transparent: Seamless integration with any background

What makes our solution stand out:

🎯 Zero Configuration & Instant Setup

• No Registration: Start tracking immediately with just your GitHub username
• One-line Integration: Single markdown line - no complex HTML required
• Per-Repository Tracking: Independent counters for each of your projects
• Official ID Compatible: Use your existing flagcounter.com ID if you have one

⚡ Modern Developer Experience

• Real-time Dashboard: Live preview with instant visual feedback
• Keyboard Shortcuts: Productivity shortcuts (Ctrl+R reset, Ctrl+E export, Ctrl+K copy)
• Import/Export Configs: Save configurations as JSON, share with team
• Quick Presets: Pre-configured setups for common use cases
• TypeScript: Full type safety throughout the codebase

🎨 Powerful Customization

• Four Display Modes: Top Countries, Flag Map, Flags From (US/CA), Mini Counter
• Multiple Themes: Default, Dark, GitHub, GitHub Dark, Transparent
• Custom Colors: Full hex color customization
• Flexible Layouts: 1-8 columns, up to 250 flags
• Custom Labels: Personalized text or hide labels entirely

🚀 Production-Ready

• High Performance: Cached responses via global CDN (< 100ms response time)
• 99.9% Uptime: Powered by Vercel's infrastructure
• Privacy First: No personal data collection or storage
• Responsive Design: Perfect display on all devices
• Open Source: MIT license, self-hostable, full code transparency

✨ Built with Next.js 15, React 19, and TypeScript for optimal performance and developer experience.

Next.js 15

React 19

TypeScript

Tailwind CSS

Vercel

Backend Stack:

• Framework: Next.js 15 with App Router
• Runtime: Node.js with ES6 modules
• Language: TypeScript with full type safety
• API Routes: Next.js API Routes (/src/app/api/route.ts) for serverless functions
• External API: Flag Counter service integration with 4 display modes
• Caching: Built-in CDN caching (1-hour cache via s-maxage)

Frontend Stack:

• Core: React 19 with TypeScript
• Styling: Tailwind CSS v3 with custom animations
• UI Components: shadcn/ui component library
• Animations: Framer Motion for smooth transitions
• State Management: React hooks (useState, useRef, custom hooks)
• Responsiveness: Mobile-first responsive design
• Pages: Landing page, Interactive dashboard, API documentation

DevOps & Infrastructure:

• Deployment: Vercel serverless platform
• Domain: Custom domain with SSL
• Monitoring: Built-in analytics and error tracking
• Performance: Global CDN with edge caching
• Build: Optimized production builds with Next.js

graph TB
    subgraph "Client Layer"
        A[GitHub Profile] --> B[Visitor Counter Image]
        C[Configuration Tool] --> D[Live Preview]
    end
    
    subgraph "Vercel Platform"
        E[API Endpoint] --> F[Parameter Processing]
        F --> G[URL Generation]
        G --> H[Flag Counter Service]
    end
    
    subgraph "External Services"
        I[Flag Counter API]
        J[Country Detection]
        K[Flag Images]
    end
    
    B --> E
    D --> E
    H --> I
    I --> J
    I --> K
    
    subgraph "Caching Layer"
        L[Vercel CDN]
        M[Browser Cache]
    end
    
    E --> L
    L --> M

sequenceDiagram
    participant U as User
    participant G as GitHub
    participant V as Vercel API
    participant F as Flag Counter
    participant C as CDN
    
    U->>G: Views GitHub Profile
    G->>V: Requests Counter Image
    V->>V: Parse Parameters
    V->>F: Generate Flag Counter URL
    F->>C: Return Flag Image
    C->>V: Cached Response
    V->>G: Redirect to Image
    G->>U: Display Counter

Performance Characteristics:

• ⚡ < 100ms API response time
• 🚀 < 1s Image loading time
• 📊 99.9% uptime reliability
• 🔄 1 hour cache duration for optimal performance

Optimization Features:

• 🎯 Smart Caching: Aggressive CDN caching strategy
• 📦 Lightweight: Zero external dependencies
• 🌐 Global CDN: Vercel's worldwide edge network
• 🔧 Efficient Processing: Minimal server computation

1. Copy the markdown code:

![](https://github-visitor-counter-tau.vercel.app/api?username=YOUR_USERNAME)

2. Paste it into your GitHub profile README.md

3. Replace YOUR_USERNAME with your GitHub username

<div align="center">
  <img src="https://github-visitor-counter-tau.vercel.app/api?username=YOUR_USERNAME" alt="Visitor Counter">
</div>

All parameters are optional except for the identifier parameters (at least one must be provided).

You must provide at least one of the following to identify your counter:

Examples:

# Global Profile Counter (tracks all profile visits)
?username=ChanMeng666

# Repository-Specific Counter (tracks specific repo visits)
?username=ChanMeng666&repo=gradient-svg-generator
# or
?repo=ChanMeng666/gradient-svg-generator

# Official Counter ID (with management dashboard)
?counterId=in9G

# Custom Project Counter
?username=ChanMeng666&project=my-portfolio

![](https://github-visitor-counter-tau.vercel.app/api?username=ChanMeng666&displayMode=topCountries)

![](https://github-visitor-counter-tau.vercel.app/api?username=ChanMeng666&displayMode=topCountries&theme=dark&maxflags=20)

![](https://github-visitor-counter-tau.vercel.app/api?username=ChanMeng666&displayMode=topCountries&columns=4&maxflags=16)

![](https://github-visitor-counter-tau.vercel.app/api?username=ChanMeng666&displayMode=flagMap&mapSize=medium)

![](https://github-visitor-counter-tau.vercel.app/api?username=ChanMeng666&displayMode=flagsFrom&flagsFromCountry=us&theme=github_dark)

![](https://github-visitor-counter-tau.vercel.app/api?username=ChanMeng666&displayMode=miniCounter&theme=transparent)

![](https://github-visitor-counter-tau.vercel.app/api?username=ChanMeng666&displayMode=topCountries&theme=github_dark&visitortype=percentage)

![](https://github-visitor-counter-tau.vercel.app/api?username=ChanMeng666&label=none)

![](https://github-visitor-counter-tau.vercel.app/api?username=ChanMeng666&label=Profile%20Views)

![](https://github-visitor-counter-tau.vercel.app/api?username=ChanMeng666&showlabels=true&columns=1&maxflags=5)

![](https://github-visitor-counter-tau.vercel.app/api?username=ChanMeng666&size=large&columns=3)

![](https://github-visitor-counter-tau.vercel.app/api?username=ChanMeng666&bg=0D1117&text=58A6FF&border=30363D)

![](https://github-visitor-counter-tau.vercel.app/api?username=ChanMeng666&showcount=false)

![](https://github-visitor-counter-tau.vercel.app/api?username=ChanMeng666&flagsfrom=us)

<!-- Different counter for gradient-svg-generator repository -->
![](https://github-visitor-counter-tau.vercel.app/api?username=ChanMeng666&repo=gradient-svg-generator)

<!-- Different counter for github-visitor-counter repository -->
![](https://github-visitor-counter-tau.vercel.app/api?username=ChanMeng666&repo=github-visitor-counter)

<!-- Use your official Counter ID from flagcounter.com -->
![](https://github-visitor-counter-tau.vercel.app/api?counterId=in9G&theme=github_dark)

Note: Replace in9G with your own Counter ID from flagcounter.com

![](https://github-visitor-counter-tau.vercel.app/api?username=ChanMeng666&theme=default)

• Background: #FFFFFF
• Text: #000000
• Border: #CCCCCC

![](https://github-visitor-counter-tau.vercel.app/api?username=ChanMeng666&theme=dark)

• Background: #0D1117
• Text: #C9D1D9
• Border: #30363D

![](https://github-visitor-counter-tau.vercel.app/api?username=ChanMeng666&theme=github)

• Background: #24292E
• Text: #FFFFFF
• Border: #444D56

![](https://github-visitor-counter-tau.vercel.app/api?username=ChanMeng666&theme=github_dark)

• Background: #161B22
• Text: #E6EDF3
• Border: #30363D

![](https://github-visitor-counter-tau.vercel.app/api?username=ChanMeng666&theme=transparent)

• Background: #FFFFFF
• Text: #000000
• Border: #FFFFFF

<div align="center">
  
  ![](https://github-visitor-counter-tau.vercel.app/api?username=YOUR_USERNAME)
  
</div>

<!-- Light Mode -->
![](https://github-visitor-counter-tau.vercel.app/api?username=YOUR_USERNAME&theme=default)

<!-- Dark Mode -->
![](https://github-visitor-counter-tau.vercel.app/api?username=YOUR_USERNAME&theme=dark)

<div align="center">
  
  ### 🌍 Visitors from around the world
  
  ![](https://github-visitor-counter-tau.vercel.app/api?username=YOUR_USERNAME)
  
  <sub>Thank you for visiting my profile!</sub>
  
</div>

https://github-visitor-counter-tau.vercel.app/api

• GET

• Redirects to Flag Counter image with specified parameters

• No explicit rate limits
• Cached for 1 hour by default

• Invalid parameters return a 400 error with usage instructions
• Missing username returns a 400 error

You can deploy your own instance of GitHub Visitor Counter:

1. Fork this repository
2. Create a Vercel account
3. Import your forked repository
4. Deploy with one click

# Clone the repository
git clone https://github.com/ChanMeng666/github-visitor-counter.git

# Navigate to project directory
cd github-visitor-counter

# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build

# Development
npm run dev          # Start development server with Vercel CLI
npm run deploy       # Deploy to production

# Testing
npm test            # Run tests (if implemented)
npm run lint        # Run linting (if configured)

# Build
npm run build       # Build for production

github-visitor-counter/
├── src/
│   ├── app/                           # Next.js App Router
│   │   ├── api/
│   │   │   └── route.ts               # Main API endpoint (Next.js API Route)
│   │   ├── dashboard/
│   │   │   └── page.tsx               # Interactive configuration dashboard
│   │   ├── api-help/
│   │   │   └── page.tsx               # API documentation page
│   │   ├── page.tsx                   # Landing page
│   │   ├── layout.tsx                 # Root layout with metadata
│   │   └── globals.css                # Global styles with Tailwind
│   ├── components/                    # React components
│   │   ├── ui/                        # shadcn/ui components
│   │   │   ├── button.tsx, card.tsx, input.tsx, select.tsx, etc.
│   │   │   └── animated-gradient-with-svg.tsx  # Custom SVG gradient
│   │   ├── landing/                   # Landing page sections
│   │   │   ├── hero-section.tsx       # Hero with CTA
│   │   │   ├── features-section.tsx   # Feature highlights
│   │   │   ├── live-demo-section.tsx  # Live demo showcase
│   │   │   ├── how-it-works-section.tsx # Process explanation
│   │   │   ├── cta-section.tsx        # Call to action
│   │   │   └── infinite-flags-scroll.tsx # Animated flag carousel
│   │   ├── dashboard/                 # Dashboard components
│   │   │   ├── config-form.tsx        # Configuration form
│   │   │   ├── preview-panel.tsx      # Live preview
│   │   │   ├── action-toolbar.tsx     # Quick actions & presets
│   │   │   ├── config-progress.tsx    # Progress indicator
│   │   │   ├── config-import-export.tsx # JSON import/export
│   │   │   ├── keyboard-shortcuts-help.tsx # Shortcuts docs
│   │   │   └── page-header.tsx        # Dashboard header
│   │   ├── shared/                    # Shared components
│   │   │   ├── header.tsx             # Site header with navigation
│   │   │   └── footer.tsx             # Site footer
│   │   └── hooks/
│   │       └── use-debounced-dimensions.tsx # Custom React hook
│   ├── lib/                           # Utility libraries (TypeScript)
│   │   ├── constants.ts               # Themes, defaults, display modes
│   │   ├── params.ts                  # Parameter parsing & validation
│   │   ├── flagCounter.ts             # URL generation (4 display modes)
│   │   └── utils.ts                   # Helper utilities
│   └── hooks/                         # Custom React hooks
│       └── useKeyboardShortcuts.ts    # Keyboard shortcut management
├── public/                            # Static assets
│   ├── *.svg                          # Logos and icon files
│   ├── llms.txt                       # AI integration guide
│   ├── robots.txt                     # SEO configuration
│   └── sitemap.xml                    # Sitemap
├── package.json                       # Next.js 15, React 19, TypeScript
├── next.config.mjs                    # Next.js configuration
├── tailwind.config.ts                 # Tailwind CSS configuration
├── tsconfig.json                      # TypeScript configuration
└── vercel.json                        # Vercel CORS configuration

Contributions are welcome! Here's how you can help improve this project:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes: Follow the existing code style
4. Test thoroughly: Ensure all functionality works
5. Submit a pull request: Provide clear description of changes

• Follow existing code patterns and conventions
• Add tests for new features when possible
• Update documentation for any API changes
• Ensure backward compatibility

• 🎨 New Themes: Add more visual themes
• 🌐 Internationalization: Add support for more languages
• 📊 Analytics: Improve visitor tracking features
• 🔧 Performance: Optimize loading and caching
• 📚 Documentation: Improve guides and examples

This project is licensed under the MIT License - see the LICENSE file for details.

• Created by Chan Meng
• Powered by Flag Counter
• Hosted on Vercel

1. Multiple Counter Types:

   • Profile Counter (username only): Tracks all visitors to your profile
   • Repository Counter (username + repo): Independent tracking for each repository
   • Official Counter ID (counterId): Use your own Flag Counter ID with management dashboard
   • Custom Project (username + project): For non-GitHub projects

2. Real Visitor Tracking: Flag Counter tracks real visitors over time. New counters start from zero and accumulate as people visit your README. This is not a bug!

3. Four Display Modes: Choose from Top Countries, Flag Map, Flags From (US/CA), or Mini Counter to suit your needs.

4. Privacy: No personal data is stored. The service only tracks country-level visitor information.

5. Caching: Counters are cached for 1 hour (s-maxage=3600) to improve performance.

6. Unique Counters: Each parameter combination creates a unique counter on Flag Counter's server.

7. TypeScript: Full type safety with TypeScript throughout the codebase.

8. Modern Stack: Built with Next.js 15, React 19, Tailwind CSS 3, and shadcn/ui.

9. Interactive Dashboard: Use /dashboard for a visual configuration experience with live preview.

10. Keyboard Shortcuts: Dashboard supports shortcuts like Ctrl+R (reset), Ctrl+E (export), Ctrl+K (copy markdown).

If you have any questions or need help, please:

• Open an issue
• Check existing issues for solutions
• Read the documentation carefully

🌍 Building Global Connections for GitHub Developers 🚀
Showcasing the worldwide reach of open source

⭐ Star us on GitHub • 🎨 Try Live Demo • 🐛 Report Issues • 💡 Request Features • 🤝 Contribute

Made with ❤️ by Chan Meng