How to make a GitHub README demo GIF with Remotion

To make a README demo GIF with Remotion, render your composition with --codec=gif, halve the frame rate with --every-nth-frame=2, and shrink it with --scale. Keep it short and loopable, and under GitHub's 10MB limit for images and GIFs.

npx remotion render Demo out/demo.gif --codec=gif --every-nth-frame=2 --scale=0.5

1. Build a short, loopable composition

A README GIF is watched in a loop, at small size, with no sound. So:

• 5–10 seconds. One command, one result.
• Big type. It will be shown at the README's width, often half your composition's.
• End where it starts. A loop that snaps from the last frame to the first looks broken; fade both ends to the same background.

For a CLI tool, a terminal that types its own command is the whole video:

// src/Root.tsx
import { Composition } from "remotion";
import { TerminalSimulator } from "@/components/snap-cn/terminal-simulator";

const Demo = () => (
  <TerminalSimulator
    intro="*deploy* in one *command.*"
    command={{ managers: ["npm", "pnpm", "yarn", "bun"], text: "npx acme deploy" }}
    lines={[
      { text: "Building…", type: "log", delay: 0 },
      { text: "✓ Deployed to acme.dev", type: "success", delay: 12 },
    ]}
  />
);

export const RemotionRoot = () => (
  <Composition
    id="Demo"
    component={Demo}
    durationInFrames={200}
    fps={30}
    width={1280}
    height={720}
  />
);

For a UI, crop a recording and push in on the part that matters with Screen Recording, and add a pointer back with Cursor Track.

2. Render it as a GIF

npx remotion render Demo out/demo.gif --codec=gif --every-nth-frame=2 --scale=0.5

What each flag does:

15fps is plenty for a README. Frame rate and dimensions are where the bytes are: half the frames at a quarter of the pixels is a far smaller file.

3. Get it under 10MB

GitHub accepts images and GIFs up to 10MB when you drag them into an issue, pull request or comment. For a README, aim far lower — a few megabytes — so the page does not stall. If the file is too big, in order:

1. Shorten it. Every second costs the same; cut the ones that are not the payoff.
2. Drop the frame rate. --every-nth-frame=3.
3. Shrink it. --scale=0.4.
4. Simplify the frame. GIF has 256 colours per frame. Gradients, blur and photos cost the most; flat backgrounds and text compress best.

4. Put it in the README

Drag the GIF into the README editor on GitHub, or commit it and reference it:

![acme deploy in one command](./docs/demo.gif)

Write the alt text as the sentence the GIF proves. It is what screen readers, search engines and anyone on a slow connection see.

When to use an MP4 instead

A GIF is huge for what it shows. An MP4 of the same clip is a fraction of the size and keeps full colour. GitHub plays .mp4, .mov and .webm uploads inline with a player — but they do not autoplay like a GIF, and a GIF also works where a README is mirrored, such as npm. Common split: a GIF in the README, the full-quality MP4 in the release notes.

Install the components:

npx shadcn@latest add @snapcn/terminal-simulator @snapcn/screen-recording

Next: how to make a changelog video in React.

FAQ