How to Add Animated SVG to Your GitHub Profile README
Step-by-step tutorial for adding animated SVGs to your GitHub profile README — typing animations, wave headers, snake contribution graphs, and custom SVG banners.
A static GitHub profile README communicates information. An animated one catches attention first. Done well, animation adds personality and visual hierarchy to your profile without distraction. Done poorly, it turns your profile into a loading spinner that never ends.
This tutorial covers the practical SVG animation techniques that work reliably on GitHub: what renders, what does not, and how to use each approach effectively.
What GitHub Actually Renders
GitHub's README renderer supports SVG images embedded via standard markdown image syntax. It does not execute JavaScript, does not support HTML <video> elements, and strips most CSS beyond what is used for basic layout.
What this means for animation:
- SVG
<animate>elements — Supported. These are the foundation of most GitHub profile animations. - SVG CSS animations — Partially supported. Simple keyframe animations work; complex animations may be stripped.
- GIF files — Fully supported. For complex animations, a GIF is often more reliable than SVG.
- JavaScript-driven animation — Not supported. No JS executes in GitHub markdown.
- Lottie animations — Not supported.
- CSS custom properties in SVG — Inconsistent support.
The reliable approach: use hosted SVG services designed specifically for GitHub READMEs, or create CSS-animated SVGs that rely only on basic keyframe syntax.
Method 1: Typing Animation with readme-typing-svg
The most widely used animated element on GitHub profile READMEs is the typing animation — text that appears to type itself out and then cycles through multiple lines.
The DenverCoder1/readme-typing-svg service generates this as an SVG hosted on a Vercel endpoint.
Basic Usage
This produces an SVG that types through each line in the lines parameter, pauses, and loops.
Configuration Parameters
| Parameter | Description | Example |
|-----------|-------------|---------|
| font | Google Font name | Fira+Code, Roboto |
| weight | Font weight | 400, 700 |
| size | Font size in pixels | 20, 28 |
| pause | Pause between cycles (ms) | 1000 |
| color | Text color hex | F77474, 58A6FF |
| background | Background color hex | 0D1117 |
| center | Center the text | true |
| vCenter | Vertical center | true |
| width | SVG width | 435 |
| lines | Semicolon-separated lines | Line+1;Line+2;Line+3 |
| duration | Type speed (ms per char) | 3000 |
| multiline | Enable multiline mode | true |
Dark Mode Version
For profiles targeting dark GitHub themes:
[](https://git.io/typing-svg)
Note the %2C (comma) and %7C (pipe) URL encoding in the lines parameter — these special characters must be encoded.
Using the Generator
Instead of constructing the URL manually, use the readme-typing-svg online generator to preview and configure your animation, then copy the generated markdown.
Method 2: Animated Header Banners with Capsule Render
Capsule Render generates visually distinctive header and footer banners — wave shapes, sloping backgrounds, egg shapes, and more — as animated or static SVGs.
Wave Header
Configuration Options
Type parameter:
waving— Wave shape (most popular)egg— Egg shape headershark— Downward triangleslice— Diagonal slicecylinder— Rounded rectanglesoft— Soft roundedrect— Rectangle
Animation parameter:
twinkling— Twinkling star effectfadeIn— Fade in on loadscaleIn— Scale in on loadblink— Blinking textblinking— Continuous blink
Color parameter:
gradient— Automatic gradient#hex— Solid colortimeAuto— Changes color based on time of dayauto— Random gradient
Matching Header and Footer
A common pattern is a header wave at the top and a matching footer wave at the bottom:
<!-- Your README content here -->
The section=footer and reversal=true parameters flip the wave to face downward.
Method 3: Snake Contribution Graph Animation
The snake contribution animation takes your GitHub contribution graph and animates a snake eating the contribution squares. It is one of the most visually distinctive profile animations.
Setup with GitHub Actions
The snake animation requires a GitHub Actions workflow to generate the SVG and store it in your repository. The workflow fetches your contribution data, generates the animated SVG, and commits it.
Step 1: Create .github/workflows/snake.yml in your profile repository:
name: Generate Snake Animation
on:
schedule:
- cron: '0 0 * * *' # Daily at midnight
workflow_dispatch:
jobs:
generate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: Platane/snk/svg-only@v3
with:
github_user_name: ${{ github.repository_owner }}
outputs: |
dist/github-snake.svg
dist/github-snake-dark.svg?palette=github-dark
- uses: crazy-max/ghaction-github-pages@v4
with:
target_branch: output
build_dir: dist
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
Step 2: After the workflow runs, embed the generated SVG in your README using the GitHub Pages URL:
For dark mode support using GitHub's picture element syntax:
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/yourusername/yourusername/output/github-snake-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/yourusername/yourusername/output/github-snake.svg">
<img alt="github contribution grid snake animation" src="https://raw.githubusercontent.com/yourusername/yourusername/output/github-snake.svg">
</picture>
Note: Replace yourusername with your actual GitHub username in all three places.
Method 4: Custom Animated SVG Banners
For complete control, you can create your own animated SVG and host it in your repository. GitHub renders SVG files directly from raw.githubusercontent.com URLs.
Minimal Animated SVG Template
<svg viewBox="0 0 800 200" xmlns="http://www.w3.org/2000/svg">
<style>
.text {
font-family: 'Courier New', monospace;
font-size: 24px;
fill: #58A6FF;
animation: fadeIn 2s ease-in-out;
}
@keyframes fadeIn {
0% { opacity: 0; transform: translateY(-10px); }
100% { opacity: 1; transform: translateY(0); }
}
.pulse {
animation: pulse 2s infinite;
}
@keyframes pulse {
0%, 100% { opacity: 1; }
50% { opacity: 0.4; }
}
</style>
<!-- Background -->
<rect width="800" height="200" fill="#0D1117" rx="10"/>
<!-- Animated text -->
<text class="text" x="50%" y="50%" text-anchor="middle" dominant-baseline="middle">
Building things with code
</text>
<!-- Pulsing accent -->
<circle class="pulse" cx="30" cy="100" r="8" fill="#58A6FF"/>
</svg>
Save this as banner.svg in your profile repository, commit it, and reference it:
CSS Animation Compatibility in GitHub SVG
GitHub strips some CSS but allows:
animationshorthand@keyframestransform(translate, scale, rotate)opacityfillandstroketransitions
Not reliably supported:
- CSS custom properties (
--variable: value) - Complex
clip-pathanimations - SVG filter animations
Placement Best Practices
Header animations (typing SVG, capsule render, custom banner) work best at the very top of your README, before any content. They set the visual tone before a visitor reads anything.
Snake animation typically goes at the bottom, after all content. It references your contribution history, so placing it at the end feels contextually appropriate.
Typing animations can also appear in the first heading area, replacing or supplementing a static name/title header.
Avoid: Multiple full-width animations stacked vertically. Two waves, a typing animation, and a snake graph all visible at once creates visual noise, not visual interest. Pick one prominent animation and use others sparingly.
Performance Considerations
Animated SVGs served from third-party services (demolab.com, capsule-render.vercel.app) add network requests when someone loads your profile. These services have rate limits and occasionally go down.
If reliability matters, host the SVGs yourself:
- Download the generated SVG locally
- Commit it to your profile repository
- Reference it via the
raw.githubusercontent.comURL
Static hosting removes the third-party dependency but also means the content is frozen — your contribution snake, for example, would need manual updates.
Frequently Asked Questions
Why isn't my SVG animation playing on GitHub?
GitHub caches SVG images aggressively. Add a cache-busting parameter to the URL (?v=2) to force a fresh fetch. Also verify the service is up — typing-svg and capsule-render have occasional downtime.
Can I use animated GIFs instead of SVGs?
Yes, and for complex animations, GIFs are often more reliable. GitHub renders GIFs fully. The trade-offs: GIFs are larger files and do not scale as crisply as SVGs on high-DPI displays.
How do I support both light and dark mode?
Use the HTML <picture> element with prefers-color-scheme media queries (as shown in the snake animation section). Most typing-svg and capsule-render configurations also accept a theme parameter for dark-mode variants.
Will animated SVGs slow down my profile page?
Animated SVGs from external services add one network request each. For most visitors on modern connections, this is imperceptible. If you embed five different animation services, the cumulative effect becomes noticeable. Keep it to one or two animated elements.
Animated elements can make your GitHub profile more memorable without making it more complex. The goal is one animation that visitors notice immediately — then your content takes over.
Want a strong static foundation before you add animations? Our AI README Generator builds the content layer: bio, project descriptions, tech stack sections, and clear structure. Add your animations on top.