Installation
Just pick how you want to grab socialshares and reference the JavaScript file.
All CSS and SVG is inlined.
Available via npm.
npm install socialshares --save
Available via Yarn.
yarn add socialshares
Available via Bower.
bower install socialshares --save
Available via unpkg.
<script src="https://unpkg.com/socialshares@2/dist/socialshares.min.js"><script>
Download compressed file and reference the JavaScript.
<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
Attribute | Values | Default |
---|---|---|
data-url | any valid url | current page url |
data-title | any string | current page title |
data-text | any string | current page meta description |
data-size | small, medium, large | medium |
data-theme | light, light-monotone, dark, brand | light |
data-icononly | none, boolean attribute | |
data-noresponsive | none, boolean attribute |
Button Attributes
Attribute | Values | Default |
---|---|---|
data-label | any string | unique to button |
data-via | any string | none |
data-icononly | none, boolean attribute |
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.
Chrome | Firefox | Opera | Safari | IE | Edge | Chrome for Android | iOS Safari |
---|---|---|---|---|---|---|---|
Yes | Yes | Yes | Yes | 10+ | Yes | Yes | Yes |
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:
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.