GitHub Watchers – An Embeddable GitHub ‘Watchers’ Button For Your Site

These days we have embeddable share and follower buttons for almost every aspect of the web, except of course for GitHub. I wanted to help remedy that, so over the weekend I created a customizable JavaScript button (that uses the GitHub API) for pulling in the watcher counts for links to any repositories you may have in a page. It gracefully degrades, comes in a few different flavours and is available to get now.

All that's needed to use the button is an a link to a specific repository (such as It doesn't need to be on your account, it can belong to anyone (which is particularly useful for groups and organizations that share repositories) and it's flexible, so it should work regardless of whether you have 8 watchers or 8,000.


To get the current release or watch the repository for future updates, click on the appropriate link below:


Getting Started

The GitHub Watchers button supports three size modes. To get started using it is include github-watchers.js (or github-watchers-nologo.js for a smaller version without the GitHub logo) in your page and simply select the class below correlating to the size/orientation of button you would like to use.

The three size modes supported which can be set via classes on any link are:

  • gitwatch – standard size. Works best for blog posts and share button-like toolbars.
  • gitwatch vertical – vertical variation. Best for project homepages.
  • gitwatch small – less wide than the standard size. Excludes the 'watchers' text.

Sample Usage

<a href="your repository URL" class="gitwatch">
your fallback link text</a>
<script type="text/javascript" src="github-watchers.js"></script>

and when populated, this might look like:

<a href=""
class="gitwatch">Watch us on GitHub</a>
<script type="text/javascript" src="github-watchers.js">

or this:

<a href=""
class="gitwatch vertical">Watch us on GitHub</a>
<script type="text/javascript" src="github-watchers.js">


To help encapsulate assets for the button, a data URI is used to store the GitHub logo. For convenience, two versions of the script are available (as seen in the download section): one which does include the logo and one which doesn't.

Note: The official Twitter retweet button is currently 19KB minified (even when optimized further with UglifyJS) so the filesizes for the above aren't *too* bad in comparison.


Should you wish to further customize the button, there are two parts of the code you may wish to look at:

  • gitwatch.text – this allows you to customize the 'watchers' text displayed on the button. Modify if you wish it to say something else or require a different language.
  • gitwatch.styles – you can modify the CSS/3 styles used for the button here (thanks to @necolas for his optimizations). Each button size (gitwatch, gitwatch.vertical, gitwatch.small) has it's own class so you can easily update on a per-button level if required.

In the future, depending on whether this button gets widely used, multiple theming options and easier customization via -data attributes may also be added.


Confirmed as working with Firefox 5-7+, Chrome 11-Canary, Safari 5+, Opera 11.5+, IE9 using BrowserStack. For some older browsers without gradient support, the buttons should work but may have have a white background (default). If you would prefer to include an image-based gradient for this, feel free to via the gitwatch class.

Known Limitations

  • The script is currently setup to only make a single call to the GitHub API for watcher counts (based on the assertion that you're unlikely to have 'watcher' links to more than one repo on a page). That said, the next version will correct this behaviour so that 'watch' counts for as many unique links as you wish can be displayed on a page.
  • There are some minor jsHint issues that are known at the moment. I'm working to iron these out for the next . release.
  • At present, clicking on a watchers count link will navigate you to the repository linked to. I would like to integrate suport for watching a repository without the need to launch a new window or navigate to the repository directly. I believe this should be possible based on and I'll work on baking this into the next version of the button.


That's it. If you have any feedback or suggestions for how the button could be improved, please feel free to either leave a comment below, submit a new issue on the project repo or send a pull request upstream. I hope this comes in useful.


Leave a Reply

Required fields are marked *.