Installation

Just pick how you want to grab socialshares and reference the JavaScript file.
All CSS and SVG is inlined.

npm install socialshares --save

yarn add socialshares

bower install socialshares --save

<script src="https://unpkg.com/socialshares@2/dist/socialshares.min.js"><script>

<script src="dist/socialshares.min.js"><script>

Usage

The following markup displays all available buttons.

Note: It's a good idea to show a maximum of 6 buttons. Read why in the FAQ.

<div class="socialshares">
  <div class="socialshares-twitter"></div>
  <div class="socialshares-facebook"></div>
  <div class="socialshares-googleplus"></div>
  <div class="socialshares-reddit"></div>
  <div class="socialshares-tumblr"></div>
  <div class="socialshares-linkedin"></div>
  <div class="socialshares-pinterest"></div>
  <div class="socialshares-slack"></div>
  <div class="socialshares-vk"></div>
  <div class="socialshares-email"></div>
  <div class="socialshares-more"></div>
</div>

Variants

There are multiple themes and sizes that you can use with data-theme, data-size, and data-icononly attributes.

<!-- Light-monotone theme (default light theme with gray icons) -->
<div class="socialshares" data-theme="light-monotone">
  <div class="socialshares-twitter"></div>
  <div class="socialshares-facebook"></div>
  <!-- Other buttons here... -->
</div>

<!-- Dark theme -->
<div class="socialshares" data-theme="dark">
  <div class="socialshares-twitter"></div>
  <div class="socialshares-facebook"></div>
  <!-- Other buttons here... -->
</div>

<!-- Brand theme -->
<div class="socialshares" data-theme="brand">
  <div class="socialshares-twitter"></div>
  <div class="socialshares-facebook"></div>
  <!-- Other buttons here... -->
</div>

<!-- Only display icons -->
<div class="socialshares" data-icononly>
  <div class="socialshares-twitter"></div>
  <div class="socialshares-facebook"></div>
  <!-- Other buttons here... -->
</div>

Configuration

You can configure socialshares with data attributes.

<!-- Container Attributes -->
<div
  class="socialshares"
  data-url="http://example.com/"
  data-title="Example title."
  data-text="Example description."
  data-size="large"
  data-theme="brand"
>
  <!-- Button Attributes -->
  <div class="socialshares-twitter" data-label="Share on Twitter" data-via="MyTwitterHandle"></div>
  <div class="socialshares-facebook" data-label="Share on Facebook"></div>
  <div class="socialshares-googleplus" data-label="Share on Google+"></div>
</div>

Container Attributes

Button Attributes

You can also configure socialshares with JavaScript.

socialshares.configure({
  url: 'Your page URL',
  title: 'Your page title',
  text: 'Your page description',
  size: 'medium',
  theme: 'light',
  icononly: false,
  responsive: true,
  dialog: {
    width: 650,
    height: 450,
  },
})

socialshares.mount() // render with new config

Methods

The socialshares JavaScript object offers multiple methods.

socialshares.configure()

Configures buttons. Example in configuration section.

socialshares.mount()

Renders buttons. Use it for single-page apps, or pass in a selector to mount to different elements. Automatically detects domready.

// re-render buttons
socialshares.mount()

// mount to different elements
socialshares.mount('.your-custom-selector')

socialshares.unmount()

Destroys buttons. This will remove all socialshares-related DOM and event listeners.

// destroy default-mounted instance
socialshares.unmount()

// destroy custom-mounted instances
socialshares.unmount('.your-custom-selector')

socialshares.removeStyles()

Remove injected CSS.

socialshares.removeStyles()

Optimization

You can gain a slight performance boost by only including the icons that you use. You will want to do this in a Webpack or Browserify environment after installing via npm or Yarn.

var socialshares = require('socialshares/dist/socialshares.noicons')
var twitterIcon = require('socialshares/dist/icons/twitter')
var facebookIcon = require('socialshares/dist/icons/facebook')

socialshares.configure({
  icons: {
    twitter: twitterIcon,
    facebook: facebookIcon,
    // others: googleplus, linkedin, pinterest, reddit, slack, tumblr, vk, more
  },
})

socialshares.mount() // render with new config

import socialshares from 'socialshares/dist/socialshares.noicons'
import twitter from 'socialshares/dist/icons/twitter'
import facebook from 'socialshares/dist/icons/facebook'

socialshares.configure({
  icons: {
    twitter,
    facebook,
    // others: googleplus, linkedin, pinterest, reddit, slack, tumblr, vk, more
  }
})

socialshares.mount() // render with new config

You can take advantage of tree-shaking in Webpack 2 or Rollup.

import socialshares from 'socialshares/dist/socialshares.noicons'
import { twitter, facebook } from 'socialshares/dist/icons'

socialshares.configure({
  icons: { twitter, facebook }
})

socialshares.mount()

Compatibility

We try to support all modern browsers. If you notice something broken, please open an issue.

FAQ

You probably have some questions about this project, here are a few common ones.

Why should I limit how many buttons I display?

While socialshares buttons are responsive and will hide labels when there isn't enough space, they currently are unable to stack on top of each other. This is because of how available space is detected to hide labels on small screens. Hopefully this will be solved in the future, but for now just display 6 buttons or less, and make sure to test on small screens.

Why is the CSS and SVG included with the JavaScript?

It was decided that v2 would be easier to setup, and keeping everything contained in a single JS file is the simplest solution. We also went with SVG over font icons for the same reason. This does mean that the buttons will not show for JS-disabled users, but sharing is typically not a core feature and you can provide a fallback with the <noscript> tag if needed.

How does socialshares help with performance and privacy?

Embedding third-party scripts from Twitter, Facebook, and other social media means that your site will have to make multiple HTTP requests to external domains, which is bad for performance. You are also giving away your visitors' browsing data by having these scripts on your site. With socialshares, you load custom buttons from your own site, which means you get full control over performance and privacy. You also get responsive and consistent-looking buttons with little effort. Read more on Sunny Singh's blog (note that the article was written before socialshares).

Who's using socialshares?

As with any project, there is a concern of whether it is safe to use in production. While still a small library, here are some sites using socialshares right now:

• Digital Bounds
• Ninjality Blog
• Sunny Singh's blog

If you are using socialshares, we'd love to know where! Tweet us and we'll add you to the list.

Where can I find previous versions?

Version 1 is no longer maintained but the docs can still be found at v1.socialshar.es.