Written by Vitalii, author of Nibbo — free browser-based tools that run locally.
A five-second GIF at the top of a README does more than three paragraphs of feature descriptions. People scrolling GitHub decide in seconds whether to star, try or close the tab.
The usual problems: the recording tool adds a watermark, the GIF ends up 40 MB, or the colors look like a 1998 website. Here's a workflow that gets a crisp, small GIF in a few minutes, with nothing to install.
Step 1: Prepare the "set"
Before recording:
- Resize the browser or terminal window to something like 1000×600. Recording a 4K screen and shrinking later wastes quality.
- Increase the font size. README GIFs are often viewed at half size on mobile.
- Hide bookmarks, notifications, other tabs, your email in the corner.
- Use a clean demo account and fake data. No real tokens in the terminal.
- Plan the action: 3–8 seconds, one feature, no hunting for the button.
Step 2: Record
The screen recorder in Nibbo uses the browser's getDisplayMedia and MediaRecorder APIs, so you can capture a single window or tab without installing anything. Microphone, system audio and webcam are optional; for a README GIF, leave them all off. There's no watermark, and the recording stays on your machine.
Record a little extra at the start and end; you'll trim it.
On macOS you can also use Cmd+Shift+5; on Windows, Win+Alt+R (Game Bar) works in many apps. Whatever produces a video file is fine for the next step.
Step 3: Convert to GIF with sane settings
Open Video to GIF, drop the recording, set the start and end to cut the dead time, and tune the settings:
| Setting | README sweet spot |
|---|---|
| Width | 720–900px |
| FPS | 10–15 (UI demos rarely need more) |
| Colors | 128–256 |
| Dither | off for flat UIs, on for gradients/photos |
| Loop | forever |
Frame rate and width drive file size far more than anything else. Going from 30 fps at 1440px to 12 fps at 800px often shrinks the GIF by 10×, with no visible loss for a UI demo.
Aim for under 5 MB. GitHub accepts larger files, but big GIFs load slowly and some mobile clients won't autoplay them.
Step 4: Add it to the README
Drag the GIF into a GitHub issue or the README editor to get a hosted URL, or commit it under docs/:
<p align="center">
<img src="docs/demo.gif" alt="Running the CLI and seeing results in the dashboard" width="800">
</p>
Write a real alt: screen readers and people on slow connections will thank you.
Consider MP4 instead
GitHub renders uploaded .mp4/.mov files as inline video players in READMEs and issues (drag-and-drop the file into the editor). A short MP4 is often 5–10× smaller than the equivalent GIF and keeps full color. The trade-off: it doesn't autoplay as a silent loop the way GIFs do. For the hero demo, GIF still wins; for a longer walkthrough, use video.
Checklist
- [ ] Small window, big font, clean desktop
- [ ] 3–8 seconds, one feature
- [ ] Trimmed, 10–15 fps, ≤900px wide
- [ ] Under ~5 MB
- [ ] Meaningful alt text
— Vitalii, author of Nibbo
Top comments (0)