sharon

A lightweight and modular social sharing library:

• a toolkit to build your own share buttons;
• opens share popups;
• counts the number of shares;
• supports 8 social networks;
• gzipped size is 1.15 KB;
• you can cherry-pick which social networks to use to make it even smaller.

Table of contents

• Setup
  • CommonJS
  • Browser
• API
  • Supported social networks
  • sharon.network(url = location.href, parameters = { title: document.title })
  • sharon.network.href(url = location.href, parameters = { title: document.title })
  • sharon.network.count(url = location.href, callback)
  • Share parameters
• Examples
  • Poor man's tweet button
  • Angular
  • React component

Setup

CommonJS

Install Sharon using npm:

npm install sharon --save

Load the whole library:

var sharon = require('sharon');

Or cherry-pick networks for smaller Webpack, Browserify or Rollup bundles:

var facebook = require('sharon/facebook');
var twitter = require('sharon/twitter');

Browser

<script src="dist/sharon.js"></script>

For the sharon.js file check the dist directory of the installed module or directly download it:

• Production version – 1.15 KB, minified and gzipped
• Source map

API

Supported social networks

Each social network has its own endpoint under the Sharon API:

Social network	Endpoint	Share count support	Share parameters
Buffer	sharon.buffer	Yes	Reference
Facebook	sharon.facebook	Yes
Google+	sharon.plus	Yes	Reference
LinkedIn	sharon.linkedin	Yes	Reference
Pinterest	sharon.pinterest	Yes	Reference
Tumblr	sharon.tumblr	Yes	Reference
Twitter	sharon.twitter		Reference
XING	sharon.xing		Reference

This table also shows which of the networks support retrieving share counts and links to the share parameters references.

sharon.network(url = location.href, parameters = { title: document.title })

• url <String> The URL to share. Defaults to the current location.
• parameters <Object> Share parameters. Default to an object with the title property equal to the current page title.

Opens a share popup.

Examples

Share the current page:

sharon.twitter();

With a custom title:

sharon.twitter({title: 'Check it out'});

Share example.com:

sharon.twitter('http://example.com');

Share example.com with a custom title:

sharon.twitter('http://example.com', {title: 'Check it out'});

sharon.network.href(url = location.href, parameters = { title: document.title })

• url <String> The URL to share. Defaults to the current location.
• parameters <Object> Share parameters. Default to an object with the title property equal to the current page title.
• Returns: <String>

Returns a share popup URL.

Examples

Get the share popup URL for the current page:

var link = sharon.twitter.href();

With a custom title:

var link = sharon.twitter.href({title: 'Check it out'});

For example.com:

var link = sharon.twitter.href('http://example.com');

For example.com with a custom title:

var link = sharon.twitter.href('http://example.com', {title: 'Check it out'});

sharon.network.count(url = location.href, callback)

• url <String> The URL of which to retrive the share count. Defaults to the current location.
• callback <Function(err, count)> A callback function that receives the count.

Retrieves the share count of a URL.

Examples

Share count for the current page:

sharon.facebook.count(function (err, count) {
  if (err) throw err;
  console.log(count);
});

For example.com:

sharon.facebook.count('http://example.com', function (err, count) {
  if (err) throw err;
  console.log(count);
});

Share parameters

When using sharon.network or sharon.network.href functions you can specify the share parameters by passing an object as the last argument. They are added to the query parameters of the share popup URL and are specifying additional features:

sharon.twitter({
  title: 'One last quarter as defending champs!',
  hashtags: ['SuperBowl', 'DenverBroncos']
});

This produces a popup with a predefined title and hashtags:

The set of the features is different for the most of the social networks. To find them out check their documentation, links to which are provided in the Supported social networks table.

There is an inconsistency between different networks: for instance, Twitter expects the text parameter to contain a link title, while Pinterest expects the description one. Sharon normalizes this behavior: when you pass a title parameter it's automatically translated into a one that corresponds to a chosen network.

Examples

Poor man's tweet button

<button type="button" onclick="sharon.twitter()">Tweet</button>

Angular

<a ng-click="share($event)" ng-href="{{href}}">Share on Facebook {{count}}</a>

$scope.href = sharon.facebook.href();

$scope.share = function (event) {
  event.preventDefault();
  sharon.facebook();
};

sharon.facebook.count(function (err, count) {
  if (err) throw err;

  $scope.$apply(function () {
    $scope.count = count;
  });
});

React component

class LinkedInShareButton extends React.Component {
  constructor(props) {
    super(props);
    this.state = {href: sharon.linkedin.href()};

    sharon.linkedin.count((err, count) => {
      if (err) throw err;
      this.setState({count});
    });
  }

  share(event) {
    event.preventDefault();
    sharon.linkedin();
  }

  render() {
    return <a onClick={this.share} href={this.state.href}>Share on LinkedIn {this.state.count}</a>;
  }
}

Changelog

1.0.0

Initial release.