Tips & Tricks: How to add a demo video in your git without adding files to the repository or hosting the files on the internet

So you just created a super cool UI element. You cannot wait to open source it and share it with your fellow developers and for the wave of shinning github stars coming your way. So you create a READ.MD file to explain how this UI element works in the most informing and easy to understand way.

You want whoever is looking at your github project to see your UI in action. You could record a video and upload it on youtube. But the viewer has to manually click on the link to watch a 10 second video in a tiny window. Some might even be too lazy to even watch the video.

Many developers have it in a GIF format so the viewer can see it as soon as he opens the page.

To show an image / GIF in your README requires you to either

  1. Host the resource on the web and link it in your README.
  2. Upload the file into the repository and directly link it in your README.


  1. Web hosting often isn't free
  2. Including it in the repository makes the repository larger than it has to be and whoever is using your project does not need your demo video cloned into their local machines.


Host it on Github using "Issues".

Open an Issue in your project

Drag your asset into the comments section

Remember your asset has to be smaller than 10MB. Which is roughly about a 30 second recording using a iPhone simulator. iPad simulator takes up more space. I would also suggest making the simulator smaller to reduce the file size.

Submit the issue

Right click on the image after it renders, click "copy Image address".

Use that link as the image source in your README.


Demo Project

Feel free to contact me!




Thanks for reading, Happy Coding!