All that's needed to use the button is an a link to a specific repository (such as http://github.com/h5bp/html5-boilerplate). 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.
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.
and when populated, this might look like:
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.
- Standard (github-watchers.js) – uses an embedded GitHub logo (5.6KB minified)
- No-logo variation (github-watchers-nologo.js) – no embedded logo (2.6KB minified)
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
- 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 http://developer.github.com/v3/repos/watching/ 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.