Skip to content

ChanMeng666/gradient-svg-generator

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

273 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Project Banner

Gradient SVG Generator

340+ animated gradient SVG banners for your GitHub README — embed a single URL, no install required.

Visual Editor · Template Gallery · API Docs


Table of Contents


Quick Start

Paste this into any Markdown file:

![Banner](https://gradient-svg-generator.vercel.app/api/svg?text=Your%20Text&template=neural-network&height=120)
  • Replace Your%20Text with your own text (spaces → %20)
  • Replace neural-network with 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.

URL Parameters

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)

🎨 Template Showcase

🌈 Pride Templates (20 Templates)

Preview Copy This Code
Progress Pride
Progress Pride
![Progress Pride](https://gradient-svg-generator.vercel.app/api/svg?text=Progress%20Pride&template=progress-pride&height=80)
Trans Pride
Trans Pride
![Trans Pride](https://gradient-svg-generator.vercel.app/api/svg?text=Trans%20Pride&template=trans-pride&height=80)
Bi Pride
Bi Pride
![Bi Pride](https://gradient-svg-generator.vercel.app/api/svg?text=Bi%20Pride&template=bi-pride&height=80)
Pan Pride
Pan Pride
![Pan Pride](https://gradient-svg-generator.vercel.app/api/svg?text=Pan%20Pride&template=pan-pride&height=80)
🏳️‍🌈 View All 20 Pride Templates
Preview Copy This Code
Lesbian Pride
Lesbian Pride
![Lesbian Pride](https://gradient-svg-generator.vercel.app/api/svg?text=Lesbian%20Pride&template=lesbian-pride&height=80)
Nonbinary Pride
Nonbinary Pride
![Nonbinary Pride](https://gradient-svg-generator.vercel.app/api/svg?text=Nonbinary%20Pride&template=nonbinary-pride&height=80)
Ace Pride
Ace Pride
![Ace Pride](https://gradient-svg-generator.vercel.app/api/svg?text=Ace%20Pride&template=ace-pride&height=80)
Genderfluid Pride
Genderfluid Pride
![Genderfluid Pride](https://gradient-svg-generator.vercel.app/api/svg?text=Genderfluid&template=genderfluid-pride&height=80)
Rainbow Pride
Rainbow Pride
![Rainbow Pride](https://gradient-svg-generator.vercel.app/api/svg?text=Rainbow%20Pride&template=pride-rainbow&height=80)
Aromantic Pride
Aromantic Pride
![Aromantic Pride](https://gradient-svg-generator.vercel.app/api/svg?text=Aro%20Pride&template=aro-pride&height=80)

🔬 Technology Templates

Preview Copy This Code
Neural Network
Neural Network
![Neural Network](https://gradient-svg-generator.vercel.app/api/svg?text=Neural%20Network&template=neural-network&height=80)
Cyber Matrix
Cyber Matrix
![Cyber Matrix](https://gradient-svg-generator.vercel.app/api/svg?text=Cyber%20Matrix&template=cyber-matrix&height=80)
Quantum Field
Quantum Field
![Quantum Field](https://gradient-svg-generator.vercel.app/api/svg?text=Quantum%20Field&template=quantum-field&height=80)
Hologram Blue
Hologram Blue
![Hologram Blue](https://gradient-svg-generator.vercel.app/api/svg?text=Hologram%20Blue&template=hologram-blue&height=80)

🌿 Nature Templates

Preview Copy This Code
Sunrise Dawn
Sunrise Dawn
![Sunrise Dawn](https://gradient-svg-generator.vercel.app/api/svg?text=Sunrise%20Dawn&template=sunrise-dawn&height=80)
Northern Aurora
Northern Aurora
![Northern Aurora](https://gradient-svg-generator.vercel.app/api/svg?text=Northern%20Aurora&template=northern-aurora&height=80)
Ocean Depths
Ocean Depths
![Ocean Depths](https://gradient-svg-generator.vercel.app/api/svg?text=Ocean%20Depths&template=ocean-depths&height=80)
Forest Mist
Forest Mist
![Forest Mist](https://gradient-svg-generator.vercel.app/api/svg?text=Forest%20Mist&template=forest-mist&height=80)

💎 Material Templates

Preview Copy This Code
Gold Luxury
Gold Luxury
![Gold Luxury](https://gradient-svg-generator.vercel.app/api/svg?text=Gold%20Luxury&template=gold-luxury&height=80)
Diamond Crystal
Diamond Crystal
![Diamond Crystal](https://gradient-svg-generator.vercel.app/api/svg?text=Diamond%20Crystal&template=diamond-crystal&height=80)
Silver Chrome
Silver Chrome
![Silver Chrome](https://gradient-svg-generator.vercel.app/api/svg?text=Silver%20Chrome&template=silver-chrome&height=80)
Emerald Gem
Emerald Gem
![Emerald Gem](https://gradient-svg-generator.vercel.app/api/svg?text=Emerald%20Gem&template=emerald-gem&height=80)

✨ Text Effect Templates

Preview Copy This Code
Luminance Glow
Luminance Glow
![Luminance Glow](https://gradient-svg-generator.vercel.app/api/svg?text=Luminance%20Glow&template=luminance-glow&height=80)
Rainbow Wave
Rainbow Wave
![Rainbow Wave](https://gradient-svg-generator.vercel.app/api/svg?text=Rainbow%20Wave&template=rainbow-wave&height=80)
Glitch Cyber
Glitch Cyber
![Glitch Cyber](https://gradient-svg-generator.vercel.app/api/svg?text=Glitch%20Cyber&template=glitch-cyber&height=80)
Typewriter Terminal
Typewriter Terminal
![Typewriter Terminal](https://gradient-svg-generator.vercel.app/api/svg?text=Typewriter%20Terminal&template=typewriter-terminal&height=80)

🎮 Gaming Templates

Preview Copy This Code
Pixel Art Retro
Pixel Art Retro
![Pixel Art Retro](https://gradient-svg-generator.vercel.app/api/svg?text=Pixel%20Art%20Retro&template=pixel-art-retro&height=80)
Neon Arcade
Neon Arcade
![Neon Arcade](https://gradient-svg-generator.vercel.app/api/svg?text=Neon%20Arcade&template=neon-arcade&height=80)
Energy Blast
Energy Blast
![Energy Blast](https://gradient-svg-generator.vercel.app/api/svg?text=Energy%20Blast&template=energy-blast&height=80)
Cyberpunk City
Cyberpunk City
![Cyberpunk City](https://gradient-svg-generator.vercel.app/api/svg?text=Cyberpunk%20City&template=cyberpunk-city&height=80)

☁️ Weather & Atmospheric Templates (12 Templates)

Preview Copy This Code
Fog Rolling
Fog Rolling
![Fog Rolling](https://gradient-svg-generator.vercel.app/api/svg?text=Fog%20Rolling&template=fog-rolling&height=80)
Monsoon Rain
Monsoon Rain
![Monsoon Rain](https://gradient-svg-generator.vercel.app/api/svg?text=Monsoon%20Rain&template=monsoon-rain&height=80)
Snowfall Drift
Snowfall Drift
![Snowfall Drift](https://gradient-svg-generator.vercel.app/api/svg?text=Snowfall%20Drift&template=snowfall-drift&height=80)
Lightning Web
Lightning Web
![Lightning Web](https://gradient-svg-generator.vercel.app/api/svg?text=Lightning%20Web&template=lightning-web&height=80)

💡 Light & Shadow Templates (12 Templates)

Preview Copy This Code
Caustic Underwater
Caustic Underwater
![Caustic Underwater](https://gradient-svg-generator.vercel.app/api/svg?text=Caustic%20Underwater&template=caustic-underwater&height=80)
Lens Flare
Lens Flare
![Lens Flare](https://gradient-svg-generator.vercel.app/api/svg?text=Lens%20Flare&template=lens-flare&height=80)
Bokeh Blur
Bokeh Blur
![Bokeh Blur](https://gradient-svg-generator.vercel.app/api/svg?text=Bokeh%20Blur&template=bokeh-blur&height=80)
God Rays
God Rays
![God Rays](https://gradient-svg-generator.vercel.app/api/svg?text=God%20Rays&template=god-rays&height=80)

🎨 Art Movement Templates (12 Templates)

Preview Copy This Code
Art Nouveau Flow
Art Nouveau Flow
![Art Nouveau Flow](https://gradient-svg-generator.vercel.app/api/svg?text=Art%20Nouveau%20Flow&template=art-nouveau-flow&height=80)
Art Deco Luxury
Art Deco Luxury
![Art Deco Luxury](https://gradient-svg-generator.vercel.app/api/svg?text=Art%20Deco%20Luxury&template=art-deco-luxury&height=80)
Impressionist Dots
Impressionist Dots
![Impressionist Dots](https://gradient-svg-generator.vercel.app/api/svg?text=Impressionist%20Dots&template=impressionist-dots&height=80)
Pop Art Halftone
Pop Art Halftone
![Pop Art Halftone](https://gradient-svg-generator.vercel.app/api/svg?text=Pop%20Art%20Halftone&template=pop-art-halftone&height=80)

🍳 Culinary & Liquid Flow Templates (12 Templates)

Preview Copy This Code
Coffee Cream
Coffee Cream
![Coffee Cream](https://gradient-svg-generator.vercel.app/api/svg?text=Coffee%20Cream&template=coffee-cream&height=80)
Wine Pour
Wine Pour
![Wine Pour](https://gradient-svg-generator.vercel.app/api/svg?text=Wine%20Pour&template=wine-pour&height=80)
Honey Drizzle
Honey Drizzle
![Honey Drizzle](https://gradient-svg-generator.vercel.app/api/svg?text=Honey%20Drizzle&template=honey-drizzle&height=80)
Chocolate Melt
Chocolate Melt
![Chocolate Melt](https://gradient-svg-generator.vercel.app/api/svg?text=Chocolate%20Melt&template=chocolate-melt&height=80)

🎯 Pattern Templates (8 Templates)

Preview Copy This Code
Candy Stripe Dream
Candy Stripe Dream
![Candy Stripe Dream](https://gradient-svg-generator.vercel.app/api/svg?text=Candy%20Stripe%20Dream&template=candy-stripe-dream&height=80)
Zigzag Energy
Zigzag Energy
![Zigzag Energy](https://gradient-svg-generator.vercel.app/api/svg?text=Zigzag%20Energy&template=zigzag-energy&height=80)
Diamond Grid
Diamond Grid
![Diamond Grid](https://gradient-svg-generator.vercel.app/api/svg?text=Diamond%20Grid&template=diamond-grid&height=80)
Heart Beat
Heart Beat
![Heart Beat](https://gradient-svg-generator.vercel.app/api/svg?text=Heart%20Beat&template=heart-beat&height=80)

✨ Metallic Effect Templates (8 Templates)

Preview Copy This Code
Copper Shine
Copper Shine
![Copper Shine](https://gradient-svg-generator.vercel.app/api/svg?text=Copper%20Shine&template=copper-shine&height=80)
Gold Shimmer
Gold Shimmer
![Gold Shimmer](https://gradient-svg-generator.vercel.app/api/svg?text=Gold%20Shimmer&template=gold-shimmer&height=80)
Chrome Flow
Chrome Flow
![Chrome Flow](https://gradient-svg-generator.vercel.app/api/svg?text=Chrome%20Flow&template=chrome-flow&height=80)
Platinum Sparkle
Platinum Sparkle
![Platinum Sparkle](https://gradient-svg-generator.vercel.app/api/svg?text=Platinum%20Sparkle&template=platinum-sparkle&height=80)

📝 Path Text Animation Templates (12 Templates)

Preview Copy This Code
Typing Path Reveal
Typing Path Reveal
![Typing Path Reveal](https://gradient-svg-generator.vercel.app/api/svg?text=Typing%20Path%20Reveal&template=typing-path-reveal&height=80)
Curved Flow
Curved Flow
![Curved Flow](https://gradient-svg-generator.vercel.app/api/svg?text=Curved%20Flow&template=curved-flow&height=80)
Spiral Text
Spiral Text
![Spiral Text](https://gradient-svg-generator.vercel.app/api/svg?text=Spiral%20Text&template=spiral-text&height=80)
Neon Flicker
Neon Flicker
![Neon Flicker](https://gradient-svg-generator.vercel.app/api/svg?text=Neon%20Flicker&template=neon-flicker&height=80)

🔷 Shape Background Templates (25 Templates)

Preview Copy This Code
Liquid Venom
Liquid Venom
![Liquid Venom](https://gradient-svg-generator.vercel.app/api/svg?text=Liquid%20Venom&template=liquid-venom&height=80)
Dreamy Sunset
Dreamy Sunset
![Dreamy Sunset](https://gradient-svg-generator.vercel.app/api/svg?text=Dreamy%20Sunset&template=dreamy-sunset&height=80)
Capsule Tech
Capsule Tech
![Capsule Tech](https://gradient-svg-generator.vercel.app/api/svg?text=Capsule%20Tech&template=capsule-tech&height=80)
Ocean Depths
Ocean Depths
![Ocean Depths](https://gradient-svg-generator.vercel.app/api/svg?text=Ocean%20Depths&template=ocean-depths&height=80)

🔮 Experimental Templates (29 Templates)

View Morphing Effects (6 Templates)
Preview Copy This Code
Liquid Mercury
Liquid Mercury
![Liquid Mercury](https://gradient-svg-generator.vercel.app/api/svg?text=Liquid%20Mercury&template=liquid-mercury&height=80)
Plasma Blob
Plasma Blob
![Plasma Blob](https://gradient-svg-generator.vercel.app/api/svg?text=Plasma%20Blob&template=plasma-blob&height=80)
Quantum Foam
Quantum Foam
![Quantum Foam](https://gradient-svg-generator.vercel.app/api/svg?text=Quantum%20Foam&template=quantum-foam&height=80)
View Fluid Dynamics (6 Templates)
Preview Copy This Code
Turbulent Waves
Turbulent Waves
![Turbulent Waves](https://gradient-svg-generator.vercel.app/api/svg?text=Turbulent%20Waves&template=turbulent-waves&height=80)
Electromagnetic Field
Electromagnetic Field
![Electromagnetic Field](https://gradient-svg-generator.vercel.app/api/svg?text=Electromagnetic%20Field&template=electromagnetic-field&height=80)
Aurora Streams
Aurora Streams
![Aurora Streams](https://gradient-svg-generator.vercel.app/api/svg?text=Aurora%20Streams&template=aurora-streams&height=80)
View Dimensional Portal (8 Templates)
Preview Copy This Code
Quantum Tunnel
Quantum Tunnel
![Quantum Tunnel](https://gradient-svg-generator.vercel.app/api/svg?text=Quantum%20Tunnel&template=quantum-tunnel&height=80)
Wormhole Transit
Wormhole Transit
![Wormhole Transit](https://gradient-svg-generator.vercel.app/api/svg?text=Wormhole%20Transit&template=wormhole-transit&height=80)
Dimensional Rift
Dimensional Rift
![Dimensional Rift](https://gradient-svg-generator.vercel.app/api/svg?text=Dimensional%20Rift&template=dimensional-rift&height=80)
View Consciousness Stream (9 Templates)
Preview Copy This Code
Thought Waves
Thought Waves
![Thought Waves](https://gradient-svg-generator.vercel.app/api/svg?text=Thought%20Waves&template=thought-waves&height=80)
Memory Fragments
Memory Fragments
![Memory Fragments](https://gradient-svg-generator.vercel.app/api/svg?text=Memory%20Fragments&template=memory-fragments&height=80)
Dream Logic
Dream Logic
![Dream Logic](https://gradient-svg-generator.vercel.app/api/svg?text=Dream%20Logic&template=dream-logic&height=80)

🏷️ GitHub Profile Templates (30 Templates)

Shimmer Badges

Colored status tags with an animated light sweep — perfect for labeling sections, features, or achievements.

Preview Markdown Code
Best Practice ![Best Practice](https://gradient-svg-generator.vercel.app/api/svg?text=Best%20Practice&template=shimmer-red&height=28)
Implemented ![Implemented](https://gradient-svg-generator.vercel.app/api/svg?text=Implemented&template=shimmer-green&height=28)
Workflow ![Workflow](https://gradient-svg-generator.vercel.app/api/svg?text=Workflow&template=shimmer-blue&height=28)
Community ![Community](https://gradient-svg-generator.vercel.app/api/svg?text=Community&template=shimmer-gold&height=28)
Claude Code ![Claude Code](https://gradient-svg-generator.vercel.app/api/svg?text=Claude%20Code&template=shimmer-orange&height=28)
Beta ![Beta](https://gradient-svg-generator.vercel.app/api/svg?text=Beta&template=shimmer-purple&height=28)
Advanced ![Advanced](https://gradient-svg-generator.vercel.app/api/svg?text=Advanced&template=shimmer-dark&height=28)

Change color: swap the template suffix (shimmer-red, shimmer-green, shimmer-blue, shimmer-gold, shimmer-orange, shimmer-purple, shimmer-dark). Change text: edit text=.

Terminal Typing

macOS-style terminal window with typing animation and blinking cursor.

Preview Markdown Code
Terminal Purple ![Terminal](https://gradient-svg-generator.vercel.app/api/svg?text=npx%20create-next-app&template=terminal-purple&height=50)
Terminal Green ![Terminal](https://gradient-svg-generator.vercel.app/api/svg?text=npm%20install%20chromaflow&template=terminal-green&height=50)
Terminal Blue ![Terminal](https://gradient-svg-generator.vercel.app/api/svg?text=git%20push%20origin%20main&template=terminal-blue&height=50)

Skill Pills

Row of rounded skill pills with shimmer overlay. Separate items with ; in text=.

Preview Markdown Code
Pills Dark ![Skills](https://gradient-svg-generator.vercel.app/api/svg?text=React;Node.js;Python;Docker&template=pills-dark&height=36)
Pills Rainbow ![Skills](https://gradient-svg-generator.vercel.app/api/svg?text=TypeScript;Go;Rust;Swift&template=pills-rainbow&height=36)
Pills Blue ![Skills](https://gradient-svg-generator.vercel.app/api/svg?text=AWS;GCP;Azure&template=pills-blue&height=36)
Pills Purple ![Skills](https://gradient-svg-generator.vercel.app/api/svg?text=Claude;GPT;Gemini&template=pills-purple&height=36)

Shimmer Banners

Wide announcement bars with animated shimmer sweep.

Preview Markdown Code
Banner Orange ![Banner](https://gradient-svg-generator.vercel.app/api/svg?text=Developed%20by%20Claude%20Code&template=banner-orange&height=32)
Banner Dark ![Banner](https://gradient-svg-generator.vercel.app/api/svg?text=Now%20Available%20on%20npm&template=banner-dark&height=32)
Banner Blue ![Banner](https://gradient-svg-generator.vercel.app/api/svg?text=Star%20this%20repo%20if%20you%20find%20it%20useful&template=banner-blue&height=32)
Banner Red ![Banner](https://gradient-svg-generator.vercel.app/api/svg?text=Breaking%20Changes%20in%20v2.0&template=banner-red&height=32)

Shimmer Text

Text with an animated internal gradient highlight — ideal for titles and headings.

Preview Markdown Code
Purple Shimmer ![Title](https://gradient-svg-generator.vercel.app/api/svg?text=Software%20Architect&template=text-shimmer-purple&height=40)
Blue Shimmer ![Title](https://gradient-svg-generator.vercel.app/api/svg?text=Full%20Stack%20Developer&template=text-shimmer-blue&height=40)
Gold Shimmer ![Title](https://gradient-svg-generator.vercel.app/api/svg?text=Open%20Source%20Contributor&template=text-shimmer-gold&height=40)

Gold Badges

Luxury metallic badges with shimmer sweep and pulsing diamond accents.

Preview Markdown Code
Gold Luxury ![Badge](https://gradient-svg-generator.vercel.app/api/svg?text=Featured%20Project&template=gold-luxury&height=40)
Platinum ![Badge](https://gradient-svg-generator.vercel.app/api/svg?text=Enterprise%20Ready&template=gold-platinum&height=40)
Rose Gold ![Badge](https://gradient-svg-generator.vercel.app/api/svg?text=Premium%20Quality&template=gold-rose&height=40)

Social / Achievement Badges

Wide achievement badges for showcasing milestones, trending status, or social proof.

Preview Markdown Code
Trending ![Trending](https://gradient-svg-generator.vercel.app/api/svg?text=GitHub%20Monthly%20Trending&template=social-trending&height=32)
Achievement Red ![Achievement](https://gradient-svg-generator.vercel.app/api/svg?text=Top%201%25%20Poster%20on%20Reddit&template=social-achievement-red&height=32)
Achievement Blue ![Achievement](https://gradient-svg-generator.vercel.app/api/svg?text=500%2B%20Stars%20on%20GitHub&template=social-achievement-blue&height=32)
Achievement Green ![Achievement](https://gradient-svg-generator.vercel.app/api/svg?text=100%25%20Test%20Coverage&template=social-achievement-green&height=32)

Repo Cards

GitHub-style two-panel cards with icon area, repo name, and shimmer overlay.

Preview Markdown Code
Repo Dark ![Repo](https://gradient-svg-generator.vercel.app/api/svg?text=my-awesome-project&template=repo-card-dark&height=48)
Repo Blue ![Repo](https://gradient-svg-generator.vercel.app/api/svg?text=chromaflow&template=repo-card-blue&height=48)
Custom GitHub Profile Effects via gradientType parameter
<!-- Shimmer badge with custom color -->

![Custom](https://gradient-svg-generator.vercel.app/api/svg?text=Your%20Label&gradientType=shimmerBadge&color0=ff6b6b&height=28)

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

![Terminal](https://gradient-svg-generator.vercel.app/api/svg?text=docker%20compose%20up&gradientType=terminalTyping&color0=22c55e&height=50)

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

![Skills](https://gradient-svg-generator.vercel.app/api/svg?text=React;Vue;Angular&gradientType=skillPills&color0=61dafb&color1=4fc08d&color2=dd0031&height=36)

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

![Title](https://gradient-svg-generator.vercel.app/api/svg?text=Your%20Title&gradientType=shimmerText&color0=1f2937&color1=f59e0b&height=40)

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

![Gold](https://gradient-svg-generator.vercel.app/api/svg?text=Award%20Winner&gradientType=goldBadge&color0=b8860b&color1=daa520&color2=ffd700&height=44)

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

![Social](https://gradient-svg-generator.vercel.app/api/svg?text=10K%20Downloads&gradientType=socialBadge&color0=16a34a&height=32)

<!-- Repo card with custom panel colors -->

![Repo](https://gradient-svg-generator.vercel.app/api/svg?text=project-name&gradientType=repoCard&color0=1e3a5f&color1=e8f0fe&height=56)

🔧 API Reference

Endpoint: https://gradient-svg-generator.vercel.app/api/svg
Interactive docs: /api-docs

Query Parameters

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.

Available Gradient Types

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');

For Developers

💻 Local Development & Self-Hosting

Prerequisites

  • Node.js 20+ (see .nvmrc — pinned engine in package.json)
  • npm (preferred — lockfile is committed) or pnpm/yarn

Quick Setup

git clone https://github.com/ChanMeng666/gradient-svg-generator.git
cd gradient-svg-generator
npm install
npm run dev

Open http://localhost:3000.

Common Commands

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 stub

Deployment

Vercel (one-click):

Deploy with Vercel

Vercel (CLI):

npm i -g vercel
vercel --prod

Docker:

docker build -t gradient-svg-generator .
docker run -p 3000:3000 gradient-svg-generator

🛠️ Tech Stack

Next.js
Next.js 16
React
React 19
TypeScript
TypeScript 5.4
Tailwind
Tailwind v4
Zod
Zod 3
Vitest
Vitest
Vercel
Vercel

Frontend 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: true for gradual migration)
  • Styling: Tailwind CSS v4 (CSS-first @theme in globals.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 UnifiedGradientGeneratorEffectRegistrySVGComposer pipeline
  • Validation: Zod schemas at the API boundary (src/core/schema/api.schema.ts)
  • Observability: Per-request X-Request-ID, X-Error-Code headers, 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

🏗️ Architecture

See docs/architecture.md and docs/REFACTORING_SUMMARY.md for the full story.

Request Lifecycle

flowchart TB
    Client["Embedded &lt;img&gt; 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
Loading

Feature-Sliced Architecture

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
Loading

Project Structure

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 Responsibilities

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, …}

🧪 Testing

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
Loading

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 UI

When 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.

⌨️ Development Guide

Adding a New Template

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.

Adding a New Effect / Gradient Type

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 entry

Manual path:

  1. Generator — add/extend a file in src/utils/gradientGenerators/
  2. Manifest — register in src/features/<category>/effect.js
  3. Config — add to GRADIENT_TYPES in src/config/gradientConfig.js (if UI-selectable)
  4. Run npm run test:contract to ensure no existing URLs regress

See docs/adding-an-effect.md for the complete walkthrough.

Adding a New Feature Category

  1. Create src/features/<name>/effect.js with a manifest
  2. Create src/features/<name>/templates.js with initial entries
  3. Update the three position-indexed tables:
    • src/core/TemplateRegistry.jsCATEGORY_REGISTRY
    • src/data/templateCategories.js → sidebar array
    • src/utils/templateUtils.jscategoryMap
  4. Add to the barrel export in src/features/index.js

Conventional Commits

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.

Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-template)
  3. Make your changes with proper documentation
  4. Run npm run test:contract to verify no regressions
  5. 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.


📄 License

MIT License — see the LICENSE file for details.

Author: Chan Meng · chanmeng.dev@gmail.com · chanmeng.org


About

【Be a star, give a star!⭐️】A Node.js service that generates animated gradient SVGs with customizable text overlays. Supports multiple gradient types, animation effects, and includes templates for both standard color schemes and pride flags. Deploy as an API endpoint to create dynamic, animated text displays with smooth gradient backgrounds.

Topics

Resources

License

Code of conduct

Stars

Watchers

Forks

Releases

No releases published

Sponsor this project

Packages

 
 
 

Contributors