340+ animated gradient SVG banners for your GitHub README — embed a single URL, no install required.
Paste this into any Markdown file:
- Replace
Your%20Textwith your own text (spaces →%20) - Replace
neural-networkwith any template name from the showcase below - Works on GitHub, GitLab, Notion, blogs — anywhere Markdown renders
Or open the Visual Editor → to pick colors, size, and animation style interactively, then copy the generated code.
| Parameter | Default | Description |
|---|---|---|
text= |
— | Display text (spaces → %20; use ; to separate multiple items for skill pills) |
template= |
— | Template name (from the showcase below) |
height= |
120 |
Height in pixels (1–10000) |
duration= |
6s |
Animation loop duration |
color0=, color1=, … |
000000 |
Gradient stop colors (hex, no #) |
gradientType= |
horizontal |
Effect style — overrides the template default; full list in API Reference |
stroke= |
— | Text stroke color (hex) |
strokeWidth= |
0 |
Text stroke width |
rotate= |
0 |
Text rotation in degrees |
textBg= |
— | Background color behind text (hex) |
Quick jump: 🌈 Pride · 🔬 Tech · 🌿 Nature · 💎 Material · ✨ Text FX · 🎮 Gaming · ☁️ Weather · 💡 Light & Shadow · 🎨 Art Movements · 🍳 Culinary · 🎯 Patterns · ✨ Metallic · 📝 Path Text · 🔷 Shapes · 🔮 Experimental · 🏷️ GitHub Profile
🏳️🌈 View All 20 Pride Templates
View Morphing Effects (6 Templates)
View Fluid Dynamics (6 Templates)
View Dimensional Portal (8 Templates)
View Consciousness Stream (9 Templates)
Colored status tags with an animated light sweep — perfect for labeling sections, features, or achievements.
Change color: swap the template suffix (
shimmer-red,shimmer-green,shimmer-blue,shimmer-gold,shimmer-orange,shimmer-purple,shimmer-dark). Change text: edittext=.
macOS-style terminal window with typing animation and blinking cursor.
Row of rounded skill pills with shimmer overlay. Separate items with ; in text=.
Wide announcement bars with animated shimmer sweep.
Text with an animated internal gradient highlight — ideal for titles and headings.
Luxury metallic badges with shimmer sweep and pulsing diamond accents.
Wide achievement badges for showcasing milestones, trending status, or social proof.
GitHub-style two-panel cards with icon area, repo name, and shimmer overlay.
Custom GitHub Profile Effects via gradientType parameter
<!-- Shimmer badge with custom color -->

<!-- Terminal with custom prompt color -->

<!-- Skill pills with custom colors per pill -->

<!-- Shimmer text with base + accent color -->

<!-- Gold badge with custom gold tones -->

<!-- Social badge — auto light/dark text based on background -->

<!-- Repo card with custom panel colors -->
Endpoint: https://gradient-svg-generator.vercel.app/api/svg
Interactive docs: /api-docs
| Parameter | Type | Default | Description | Example |
|---|---|---|---|---|
text |
string | (optional) | Display text | text=Hello%20World |
height |
number | 120 |
SVG height in pixels (1–10000) | height=150 |
template |
string | — | Template name | template=neural-network |
gradientType |
string | horizontal |
Effect style (default when no template is set) | gradientType=spiral |
duration |
string | 6s |
Animation duration (CSS time) | duration=8s |
animation |
string | none |
Animation mode | animation=pulse |
stroke |
string | — | Text stroke color (hex without #) |
stroke=ffffff |
strokeWidth |
number | 0 |
Text stroke width | strokeWidth=2 |
textBg |
string | — | Background color behind text | textBg=000000 |
rotate |
number | 0 |
Rotation in degrees | rotate=45 |
color0, color1, … |
string | 000000 |
Gradient colors — collected sequentially | color0=ff0000&color1=00ff00 |
Malformed values (e.g. height=abc) return HTTP 400 with X-Error-Code: INVALID_QUERY.
Full list of 176 gradientType values
// Basic Types (7)
('linear', 'radial', 'conic', 'diamond', 'reflected', 'square', 'ellipse');
// Text Effects (5)
('luminance', 'rainbow', 'textBox', 'glitch', 'typewriter');
// Future Tech (6)
('hologram', 'quantum', 'laserGrid', 'neuralNet', 'plasma', 'dataStream');
// Artistic (7)
('watercolor', 'oilPaint', 'inkSplash', 'mosaic', 'abstractGeo', 'graffiti', 'vintage');
// Luxury Materials (7)
('goldFoil', 'diamond', 'marble', 'platinum', 'roseGold', 'crystal', 'velvet');
// Organic Nature (8)
('flowingWater', 'flame', 'clouds', 'aurora', 'oceanWaves', 'forest', 'lightning', 'mountainMist');
// Gaming Effects (8)
('pixelArt',
'neonArcade',
'energyBlast',
'speedLines',
'bossBattle',
'powerUp',
'cyberpunk',
'retroWave');
// Morphing Effects (6)
('liquidMorphing',
'plasmaMorphing',
'cosmicMorphing',
'bioMorphing',
'quantumMorphing',
'lavaMorphing');
// Fluid Dynamics (6)
('turbulentWaves',
'electromagneticWaves',
'auroraWaves',
'soundWaves',
'cryogenicWaves',
'solarWaves');
// Dimensional Effects (6)
('portalDistortion',
'hypercubeProjection',
'wormholeEffect',
'fractalDimension',
'multiverseOverlap',
'realityDistortion');
// Dimensional Portal (7)
('quantumTunnel',
'parallelDimension',
'wormholePortal',
'dimensionalTear',
'holographicGrid',
'voidDistortion',
'astralPlane');
// Digital Life (8)
('aiConsciousness',
'bioDigitalMerge',
'quantumDNA',
'digitalEvolution',
'syntheticSoul',
'cyberSymbiosis',
'neuralStorm',
'digitalGenome');
// Cyber Aesthetics (9)
('neonCityscape',
'dataMatrix',
'cyberpunkShadow',
'holographicUI',
'pixelCorruption',
'chromeFinish',
'viralSpread',
'encryptionField',
'arOverlay');
// Consciousness Stream (9)
('thoughtWaves',
'memoryFragments',
'dreamLogic',
'emotionalSpectrum',
'meditativeCalm',
'anxietySpiral',
'egoDissolution',
'psychedelicInsight',
'collectiveUnconscious');
// Weather & Atmosphere (7)
('fogRolling',
'monsoonRain',
'snowfallDrift',
'sandstormSwirl',
'tornadoVortex',
'lightningWeb',
'prismRefraction');
// Light & Shadow (7)
('causticUnderwater',
'venetianBlind',
'stainedGlass',
'lensFlare',
'bokehBlur',
'godRays',
'eclipseCorona');
// Art Movements (7)
('artNouveauFlow',
'artDecoLuxury',
'bauhausMinimal',
'impressionistDots',
'cubistFragments',
'surrealistMelt',
'popArtHalftone');
// Culinary & Liquid (7)
('coffeeCream',
'winePour',
'honeyDrizzle',
'chocolateMelt',
'caramelSwirl',
'tieDye',
'marbleMixing');
// Pattern Based (8)
('candystripe',
'patternZigzag',
'diamondPattern',
'heartsPattern',
'checkered',
'diagonalFlow',
'geometricPulse',
'patternWave');
// Metallic Effects (9)
('copperMetallic',
'shineShimmer',
'neonPulse',
'aquaFlow',
'sparkleEffect',
'chromeFlow',
'bronzeGleam',
'platinumSparkle',
'steelAqua');
// Path Text Animation (12)
('typingPathReveal',
'curvedFlow',
'spiralText',
'waveTextPath',
'charByChar',
'wordCascade',
'lineSequence',
'fadeInPath',
'handwriting',
'brushStroke',
'neonFlicker',
'elasticBounce');
// Blob & Shape Effects (8)
('blobMorph',
'liquidBlob',
'organicBlob',
'layeredWaves',
'blurMotion',
'dreamyCircles',
'abstractBlur');
// Shape Backgrounds (7)
('cylinder', 'softRounded', 'eggShape', 'sliceShape', 'speechBubble', 'sharkTeeth', 'largeRounded');
// GitHub Profile Effects (8)
('shimmerBadge',
'terminalTyping',
'skillPills',
'shimmerBanner',
'shimmerText',
'goldBadge',
'socialBadge',
'repoCard');- Node.js 20+ (see
.nvmrc— pinned engine inpackage.json) - npm (preferred — lockfile is committed) or pnpm/yarn
git clone https://github.com/ChanMeng666/gradient-svg-generator.git
cd gradient-svg-generator
npm install
npm run devOpen http://localhost:3000.
npm run dev # Next.js dev server on :3000
npm run build # Production build
npm start # Run production build
npm run typecheck # tsc --noEmit (strict mode)
npm run lint # ESLint 9 flat config
npm run format # Prettier write
npm run test # Full Vitest run
npm run test:watch # Vitest watch mode
npm run test:contract # SVG byte-parity snapshot tests (the public-API gate)
npm run create:effect # Scaffold a new effect + manifest + template stubVercel (one-click):
Vercel (CLI):
npm i -g vercel
vercel --prodDocker:
docker build -t gradient-svg-generator .
docker run -p 3000:3000 gradient-svg-generatorFrontend Stack:
- Framework: Next.js 16 (Pages Router) with SSR for
/api/svg - UI Library: React 19 with Hooks and Server Components where available
- Language: TypeScript 5.4 (
strict: true,allowJs: truefor gradual migration) - Styling: Tailwind CSS v4 (CSS-first
@themeinglobals.css) + CSS Modules + shadcn/ui primitives - Icons: Lucide React + React Icons
- State Management: Zustand v5 split across 3 slices (
config,template,ui) with persistence - Animation: Framer Motion (UI) + native CSS/SVG SMIL (gradient effects)
- Data / Search:
@tanstack/react-query,@tanstack/react-virtual,fuse.js
Backend / API Stack:
- Runtime: Node.js 20+ on Next.js API Routes (serverless on Vercel)
- SVG Engine: Custom
UnifiedGradientGenerator→EffectRegistry→SVGComposerpipeline - Validation: Zod schemas at the API boundary (
src/core/schema/api.schema.ts) - Observability: Per-request
X-Request-ID,X-Error-Codeheaders, structured console logs - Filters: 12 per-primitive modules under
src/core/filters/(blur, turbulence, glow, lighting, …)
Quality & Tooling:
- Testing: Vitest + jsdom + Testing Library + contract snapshot harness
- Lint / Format: ESLint 9 (flat config) + typescript-eslint + Prettier
- Pre-commit: Husky + lint-staged (
eslint --fix+prettier --write) - Scaffolding:
npm run create:effect— generates effect + manifest + template stub
DevOps & Deployment:
- Deployment: Vercel (primary) · Docker · any Node 20+ host
- Performance: Vercel Edge Network CDN · immutable caching on template outputs
- PWA: Service Worker v3 (
public/sw.js) caches static shell;/api/*is never cached
See
docs/architecture.mdanddocs/REFACTORING_SUMMARY.mdfor the full story.
flowchart TB
Client["Embedded <img> tag<br/>(GitHub README, blog, etc.)"]
API["src/pages/api/svg.ts<br/>Typed handler · Zod validation · X-Request-ID"]
Schema["SvgQuerySchema (Zod)<br/>src/core/schema/api.schema.ts"]
UGG["UnifiedGradientGenerator.js<br/>Orchestrator"]
TR["TemplateRegistry.js<br/>Static imports · CATEGORY_REGISTRY"]
ER["EffectRegistry.js<br/>name → generator"]
Gen["Effect generator<br/>(src/utils/gradientGenerators/*.js)"]
SC["SVGComposer.js<br/>Final SVG assembly"]
Filters["src/core/filters/*<br/>blur · turbulence · glow · lighting · …"]
Headers["setAiFriendlyHeaders()<br/>Cache-Control immutable · X-API-Usage · X-Request-ID"]
Client -->|"GET /api/svg?text=Hi&template=aurora-borealis"| API
API -->|safeParse| Schema
Schema -->|valid| UGG
Schema -.->|invalid| Reject["400 + X-Error-Code: INVALID_QUERY"]
UGG -->|getTemplate| TR
TR -->|colors · gradientType · duration| UGG
UGG -->|get effect| ER
ER -->|generator ref| UGG
UGG -->|generate| Gen
Gen -->|gradientDef · elements| SC
SC -->|getAllFilters| Filters
SC -->|SVG string| UGG
UGG --> Headers
Headers -->|"Content-Type: image/svg+xml"| Client
Each gradient category is a vertical slice under src/features/<name>/:
flowchart LR
subgraph features["src/features/ — 19 categories + _shared"]
direction TB
Manifest["effect.js<br/>effect metadata · generator refs"]
Templates["templates.js<br/>colors · gradientType · duration"]
Palettes["_shared/palettes.js<br/>pride · rainbow · seasonal"]
Primitives["_shared/svgPrimitives.js<br/>animatedLinearGradient · animatedRadialGradient"]
end
subgraph generators["src/utils/gradientGenerators/ — 22 files"]
BasicGen["basicGradients.js"]
ArtGen["artisticGradients.js"]
OrgGen["organicGradients.js"]
OtherGen["…19 more"]
end
subgraph core["src/core/"]
UGG2["UnifiedGradientGenerator"]
ER2["EffectRegistry"]
TR2["TemplateRegistry"]
FL["filters/ — 12 modules"]
SCH["schema/ — Zod schemas"]
end
Manifest --> ER2
Templates --> TR2
Templates --> Palettes
Manifest --> generators
generators --> Primitives
UGG2 --> ER2
UGG2 --> TR2
UGG2 --> FL
gradient-svg-generator/
├── src/
│ ├── pages/ # Next.js pages — all .tsx post-Phase 7
│ │ ├── _app.tsx / _document.tsx
│ │ ├── index.tsx # Home
│ │ ├── create.tsx # Full editor
│ │ ├── templates.tsx # Gallery (virtualized)
│ │ ├── api-docs.tsx # API reference
│ │ └── api/svg.ts # Typed handler + Zod validation
│ ├── core/ # SVG engine — legacy JS for parity
│ │ ├── UnifiedGradientGenerator.js
│ │ ├── EffectRegistry.js
│ │ ├── TemplateRegistry.js
│ │ ├── SVGComposer.js
│ │ ├── filters/ # 12 per-primitive modules
│ │ └── schema/ # Zod schemas (TypeScript)
│ ├── features/ # 19 vertical slices + _shared/
│ │ ├── basic · pride · nature · tech · art
│ │ ├── luxury · gaming · material · animation
│ │ ├── fluids · specialty · lightShadow
│ │ ├── pattern · metallic · pathText · shape
│ │ ├── emotion · culinaryLiquid · githubProfile
│ │ └── _shared/palettes.js · svgPrimitives.js
│ ├── utils/gradientGenerators/ # 22 generator files
│ ├── components/ # 20 .tsx + 1 .ts
│ ├── hooks/ # 8 hooks, all TypeScript
│ ├── store/ # Zustand v5 — 3 slices
│ └── config/ # gradientConfig.js (176 types)
├── tests/
│ ├── contract/svg-parity.test.ts # ~72 URL byte-parity snapshots
│ └── unit/
└── docs/
├── architecture.md
└── adding-an-effect.md
| Module | Language | Purpose |
|---|---|---|
src/pages/api/svg.ts |
TS | HTTP entry point. Zod validation, error codes, request ID |
src/core/schema/api.schema.ts |
TS | Runtime query contract |
src/core/UnifiedGradientGenerator |
JS | Orchestration between template/effect lookup + composer |
src/core/EffectRegistry |
JS | registerEffect() / getEffect() / category indexing |
src/core/TemplateRegistry |
JS | Static imports of all 19 feature template modules |
src/core/SVGComposer |
JS | Assembles SVG string with filters + animations |
src/core/filters/* |
JS | Per-primitive filter factories |
src/utils/gradientGenerators/* |
JS | 22 category-scoped gradient generator implementations |
src/features/<category>/effect.js |
JS | Feature manifest — declarative effect registration |
src/features/<category>/templates.js |
JS | Array of template entries {name, label, colors, …} |
The test strategy has two layers: unit tests for generators/schemas and a contract snapshot harness that guards the public SVG output.
flowchart LR
subgraph unit["tests/unit/"]
U1["api-svg-schema.test.ts<br/>Zod validation rules"]
U2["githubProfileGradients.test.ts"]
end
subgraph contract["tests/contract/"]
C1["svg-parity.test.ts<br/>~72 representative URLs"]
C2["__snapshots__/<br/>byte-identical SVG output"]
C1 --> C2
end
subgraph tooling["Vitest runtime"]
V1["jsdom environment"]
V2["tests/setup.ts"]
V3["v8 coverage · html + lcov reporters"]
end
U1 --> tooling
U2 --> tooling
C1 --> tooling
tests/contract/svg-parity.test.ts hits ~72 representative URLs through the handler, normalizes auto-generated IDs to stable markers, and snapshots the resulting SVG. Any refactor that changes an existing template's byte output fails CI.
npm run test:contract # Run the parity gate
npm run test # Full Vitest run (unit + contract)
npm run test:watch # Watch mode
npm run test:ui # Vitest UIWhen adding a new effect: additive changes are safe. Refactors that touch shared code must preserve bytes — update snapshots deliberately, never with --update as a reflex.
Templates live co-located with their generator. Add an entry to the relevant feature folder:
// src/features/tech/templates.js
import { palettes } from '../_shared/palettes';
export default [
// ... existing entries
{
name: 'my-awesome-template',
label: 'My Awesome Template',
colors: ['ff0080', '7928ca', '0070f3'],
gradientType: 'hologram',
animationDuration: '6s',
description: 'A futuristic gradient with hologram effect',
},
];The template auto-registers via CATEGORY_REGISTRY in src/core/TemplateRegistry.js.
The fastest path is the scaffolding CLI:
npm run create:effect
# Prompts for category, effect name, and seed template.
# Generates: effect manifest + generator stub + template entryManual path:
- Generator — add/extend a file in
src/utils/gradientGenerators/ - Manifest — register in
src/features/<category>/effect.js - Config — add to
GRADIENT_TYPESinsrc/config/gradientConfig.js(if UI-selectable) - Run
npm run test:contractto ensure no existing URLs regress
See docs/adding-an-effect.md for the complete walkthrough.
- Create
src/features/<name>/effect.jswith a manifest - Create
src/features/<name>/templates.jswith initial entries - Update the three position-indexed tables:
src/core/TemplateRegistry.js→CATEGORY_REGISTRYsrc/data/templateCategories.js→ sidebar arraysrc/utils/templateUtils.js→categoryMap
- Add to the barrel export in
src/features/index.js
feat(phase-7.8): Zod-validate /api/svg query params + 400 on bad height
refactor(phase-7.7): drop orphaned CSS (2 files, -191 LOC)
fix: ...
docs: ...
chore: ...
Husky pre-commit hooks run eslint --fix and prettier --write on staged files via lint-staged.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-template) - Make your changes with proper documentation
- Run
npm run test:contractto verify no regressions - Submit a pull request with a clear description
For major changes, open an issue first to discuss your ideas.
Areas for contribution: new template designs, additional gradient types, UI/UX improvements, performance optimizations, documentation, bug fixes.
MIT License — see the LICENSE file for details.
Author: Chan Meng · chanmeng.dev@gmail.com · chanmeng.org