A pull request that changes UI is much easier to review when the reviewer can see the before and after. A short GIF does that inline: it loops in the PR description, it needs no click, and it also works in places where video does not play.

The catch is size. GitHub's documentation lists a 10 MB maximum for images and GIFs attached to issues, pull requests and comments (check the current "Attaching files" page; limits change). A careless 30-second full-screen recording blows past that easily. This walkthrough records a short clip, trims it, and checks the file before you drag it into the PR.

Disclosure: I work with the team behind LoopGIF, and the recorder used below is LoopGIF's free browser tool. AI assistance was used to draft this post; the steps and the script were checked by hand. Any recorder works — the size rules are the same.

1. Decide what the GIF has to prove

Before you record, write one sentence: "Clicking Save with an empty title shows the inline error instead of a toast." If the GIF needs more than one sentence, it probably needs two GIFs (before / after) rather than one long one.

Practical limits that keep files small:

  • One interaction per clip. Reviewers scan; 5–10 seconds is usually enough.
  • Record a region or a single tab, not the whole screen. Pixel area is the biggest driver of GIF size.
  • 10–12 fps is plenty for UI. Clicks and form errors don't need 30 fps.

2. Record the clip in the browser

Open the LoopGIF screen recording to GIF tool. It runs in a desktop browser and uses the browser's own "share a tab, window or screen" prompt; the page says the recording stays in the tab and nothing is uploaded.

  1. Pick a frame rate: 10, 12 or 15 fps. The recorder stops by itself at 300 frames (30 s at 10 fps, 25 s at 12 fps, 20 s at 15 fps).
  2. Press Start recording and choose the tab that shows your app — sharing a single tab instead of the whole screen keeps the frame small and avoids leaking other windows.
  3. Reproduce the bug once, then press Stop.

No audio is captured, which is what you want for a PR anyway.

3. Trim and size it

  • Drag the start and end sliders so the clip starts one beat before the click and ends right after the result appears. Every idle second you cut is bytes saved.
  • Choose a width. GitHub's PR column is far narrower than a 1440 px screen, so a 640 px wide GIF still reads clearly.
  • Choose Balanced for crisp UI text, or Smaller file if you are near the limit.
  • Press Create GIF. The tool shows the size, frame count and length of the result before you download it.

4. Check the file before you upload

If you want a quick sanity check (or you are adding GIFs in CI docs), this script prints what matters. It needs Python 3 and Pillow (pip install pillow):

# check_pr_gif.py import sys from pathlib import Path from PIL import Image, ImageSequence LIMIT = 10 * 1024 * 1024 # GitHub: 10MB for images and gifs (check current docs) path = Path(sys.argv[1]) with Image.open(path) as im: durations = [f.info.get("duration", 0) for f in ImageSequence.Iterator(im)] width, height = im.size size = path.stat().st_size total_ms = sum(durations) print(f"{width}x{height}px, {len(durations)} frames, {total_ms/1000:.1f}s") print(f"{size/1024/1024:.2f} MB of {LIMIT/1024/1024:.0f} MB") if size > LIMIT: print("Too big: trim the clip, lower the width, or use 'Smaller file'.") sys.exit(1) 
python check_pr_gif.py save-error.gif # 640x400px, 72 frames, 7.2s (example output; your numbers will differ) 

5. Put it in the PR

Drag the GIF into the PR description. GitHub uploads it and inserts the Markdown for you. Then add alt text that says what happens, because "demo" tells a screen-reader user nothing:

**Before** — empty title shows a toast that disappears: ![Clicking Save with an empty title shows a toast that vanishes after 2 seconds](before.gif) **After** — the error stays next to the field: ![Clicking Save with an empty title shows an inline error under the Title field](after.gif) 

When a GIF is the wrong choice

  • Longer than ~30 seconds, or you need audio: attach an MP4 instead. GitHub plays videos inline in PRs (10 MB on free plans, 100 MB on paid plans, per the same docs page).
  • Photo-like content (video calls, camera footage): GIF's 256-colour palette makes these large and blotchy; MP4 is better.
  • README demos that must also show on npm or a docs site: a GIF committed to the repo is still the most portable option.

Checklist

  • [ ] One interaction, 5–10 s
  • [ ] Single tab or region, ~640 px wide
  • [ ] 10–12 fps
  • [ ] Under 10 MB (check before uploading)
  • [ ] Alt text that describes the behaviour