CoffeeScript JavaScript HTML CSS
Switch branches/tags
Nothing to show
Clone or download
Latest commit ba1379c Jul 23, 2018

README.md

github-buttons

CircleCI Codecov

To get started, checkout buttons.github.io!

Documentation

Quick Start

The easiest way to get started is to use the github:button generator.

Components

Basic Usage (without component)

Markup Syntax

<!-- Place this tag where you want the button to render. -->
<a class="github-button"
   href="{{ link }}"
   title="{{ title }}"
   data-icon="{{ octicon }}"
   data-size="{{ size }}"
   data-show-count="{{ show count }}"
   data-text="{{ text }}"
   aria-label="{{ aria label }}"
   >{{ text }}</a>
<!-- Place this tag in your head or just before your close body tag. -->
<script async defer src="https://buttons.github.io/buttons.js"></script>

Config

Attribute Description
href GitHub link for the button.
title title attribute for the button's <iframe>.
data-icon octicon-mark-github by default. A subset of Octicons is bundled.
data-size None by default or large.
data-show-count false by default or true. The dynamic count is generated based on detected button type.
data-text Text displayed on the button. It defaults to the text content within the link.
aria-label Aira label for the button link.
Built-in Button Types

Button type is detected through button's href attribute.

  • https://github.com/:user (follow)
  • https://github.com/:user/:repo (star)
  • https://github.com/:user/:repo/subscription (watch)
  • https://github.com/:user/:repo/fork (fork)
  • https://github.com/:user/:repo/issues (issues)
  • https://github.com/:user/:repo/issues/new (issues)

Tailing slash, query string, and hash in the href are handled.

  • https://github.com/:user/ (follow)
  • https://github.com/:user?tab=repositories (follow)
  • https://github.com/:user/:repo#license (star)
  • https://github.com/:user/:repo/#license (star)

Advanced Usage

Import as a Module

This module works with CommonJS or AMD loader.

The default behavior of including the <script> tag is to render all the <a class="github-button"> tags on the page. This behavior is turned off when loading as a module.

var GitHubButtons = require('github-buttons')

It is recommended to use a module bundler rather than a module loader.

Using button.js with RequireJS

Loading this module as <script> tag together with require.js will cause an error.

This is intentional. To avoid the ambiguity on default behavoir, you should load the module via RequireJS API like following:

require(['https://buttons.github.io/buttons.js'], function (GitHubButtons) {
  GitHubButtons.render()
});

Render a Button

To create buttons dynamically, you will use the render() function, which is a named export of this module.

GitHubButtons.render(target, config)
  • target is a DOM node to be replaced by a button.
  • config is an object containing the attributes.

To append the button to a parent node instead, you need to create a placeholder as target.

GitHubButtons.render(parentNode.appendChild(document.createElement('span')), config)

Alternatively, config can be read from the target if it is an Anchor (<a>) with attributes.

GitHubButtons.render(target)

Development

Clone

git clone https://github.com/ntkme/github-buttons.git
cd github-buttons && npm install

Build

npm run build

Test

npm test

See also

License

See LICENSE.md.