Documentation

How to use GitHub Contribution Gravity Lens.

Quick Start

The simplest way to generate a Gravity Lens visualization is to use this web UI. Enter your GitHub username and click Generate.

You can also use the CLI tool directly:

npx github-contribution-gravity-lens --user <username> --token <GitHub Personal Access Token> --theme <theme-name>

Embedding in README

After generating your SVG, copy the embed code and paste it into your README.md:

Markdown

![Gravity Lens](https://gravity-lens.rujuu.com/api/svg/YOUR_USERNAME?theme=deep-space)

HTML

<img src="https://gravity-lens.rujuu.com/api/svg/YOUR_USERNAME?theme=deep-space" alt="Gravity Lens" />

GitHub Actions

Automate SVG generation with GitHub Actions for always up-to-date contribution visualizations.

View GitHub Actions setup guide →

Themes

Six built-in themes are available, each designed for different aesthetics:

  • github — Classic GitHub green contribution colors
  • deep-space — Purple and blue cosmic theme (default)
  • monochrome — Elegant grayscale
  • solar-flare — Warm orange and red
  • event-horizon — Dark with crimson accents
  • paper-light — Light background for light-themed READMEs

Advanced Options

Strength (0 - 1)
Controls the intensity of the gravitational warp effect. Higher values create more dramatic distortions around active contribution areas.
Duration (1 - 60 seconds)
Length of the SVG animation cycle. The animation loops continuously.
Clip Percent (50 - 100)
Percentile threshold for anomaly detection. Lower values create more anomaly highlights.

Links

GitHub Repository →npm Package →