shareon/README.md

188 lines
5.9 KiB
Markdown
Raw Normal View History

# Shareon
2020-03-25 11:32:25 -04:00
<img src="./assets/logo.svg" align="right" alt="Shareon logo — the Postal Horn emoji" width="96" height="96">
2020-03-25 11:32:25 -04:00
> Lightweight, stylish, and ethical share buttons
2020-03-25 11:32:25 -04:00
2020-07-04 17:02:35 -04:00
- **Small.** Dependency-free. CSS+JS bundle is only 6 KB minified and gzipped.
- **Stylish.** Uses official vector logos and colours with no visual mess.
2020-06-26 11:32:02 -04:00
- **Ethical.** Embeds no tracking code. JS is required only for the setup.
2020-03-25 11:32:25 -04:00
2023-03-20 14:43:35 -04:00
<a href="https://shareon.js.org/"><img src="./assets/demo@2x.png" height="84" width="477" alt="Shareon demo screenshot"></a>
2020-03-25 19:38:54 -04:00
See the live demo at [shareon.js.org](https://shareon.js.org)
2020-03-25 19:38:54 -04:00
## Install
Simply load the needed files from the CDN:
2020-03-25 19:38:54 -04:00
```html
2022-02-08 12:56:39 -05:00
<link
href="https://cdn.jsdelivr.net/npm/shareon@2/dist/shareon.min.css"
2022-02-08 12:56:39 -05:00
rel="stylesheet"
/>
<script
src="https://cdn.jsdelivr.net/npm/shareon@2/dist/shareon.iife.js"
defer
init
2022-02-08 12:56:39 -05:00
></script>
2020-03-25 19:38:54 -04:00
```
- `defer` makes sure Shareon is loaded after HTML is parsed
- `init` will automatically initialize Shareon buttons
2020-03-25 19:38:54 -04:00
### Do not auto-initialize
2020-03-25 19:38:54 -04:00
Remove the `init` attribute and initialize Shareon when you need it:
```html
<script
src="https://cdn.jsdelivr.net/npm/shareon@2/dist/shareon.iife.js"
defer
></script>
2020-07-26 08:40:37 -04:00
<script>
// do something
Shareon.init();
</script>
```
2020-07-26 08:40:37 -04:00
### Use ESM build
2020-07-26 08:40:37 -04:00
There is also a ESM build for the browsers, which doesn't support
auto-initialization:
2020-07-26 08:40:37 -04:00
```html
<script type="module">
import { init } from "https://cdn.jsdelivr.net/npm/shareon@2/dist/shareon.es.js";
// do something
init();
</script>
2020-07-26 08:40:37 -04:00
```
### Bundle with Node
2020-07-26 08:40:37 -04:00
You can also install Shareon using your favourite package manager and include it
in your source files:
2020-07-26 08:40:37 -04:00
```sh
pnpm add shareon # or `npm install`, or `yarn add`
```
```js
import { init } from "shareon";
import "shareon/css"; // most bundlers will transpile this CSS
init();
2020-07-26 08:40:37 -04:00
```
CommonJS imports are also supported:
2020-07-26 08:40:37 -04:00
```js
const Shareon = require("shareon");
require("shareon/css"); // most bundlers will transpile this CSS
2020-07-26 08:40:37 -04:00
Shareon.init();
2020-03-25 19:38:54 -04:00
```
2020-03-25 19:44:31 -04:00
## Usage
Create a container with class `shareon` and populate it with elements, class
2023-03-20 14:21:42 -04:00
names of which match the names of the social networks (or `copy-url`, for the
'Copy URL' button:
2020-03-25 11:32:25 -04:00
2020-03-25 19:25:17 -04:00
```html
<div class="shareon">
2022-02-08 12:56:39 -05:00
<a class="facebook"></a>
<a class="linkedin"></a>
<a class="mastodon"></a>
<!-- FB App ID is required for the Messenger button to function -->
<a class="messenger" data-fb-app-id="0123456789012345"></a>
<a class="odnoklassniki"></a>
<a class="pinterest"></a>
<a class="pocket"></a>
<a class="reddit"></a>
<a class="telegram"></a>
<a class="twitter"></a>
<a class="viber"></a>
<a class="vkontakte"></a>
<a class="whatsapp"></a>
2023-03-20 14:21:42 -04:00
<a class="copy-url"></a>
2020-03-25 19:44:31 -04:00
</div>
```
Shareon will populate these `<a>` elements with correct `href` attributes.
### Use with `<button>`s
You can use `<button>` (or any other element) instead of `<a>`s. In this case,
Shareon will create an `onclick`-listener for each button. **I do not recommend
doing this**, as this is not so good for semantics.
### Share metadata
2020-03-25 20:43:16 -04:00
By default, the URL and the title of the active page will be shared. You can
customize it with `data-` attributes. These can be applied on a specific button
or on the whole `.shareon` container:
2020-03-25 19:44:31 -04:00
```html
<div class="shareon" data-url="https://custom.url/for-this-page">
2022-02-08 12:56:39 -05:00
<a class="facebook" data-title="Custom Facebook title"></a>
<a class="twitter" data-title="Custom Twitter title"></a>
2020-03-25 19:44:31 -04:00
</div>
```
Apart from the URL and title, some networks support extra parameters:
- you **MUST** add `data-fb-app-id` to the FB Messenger button to make sharing
even possible
- add `data-media` to an Odnoklassniki, Pinterest, or VK button to customize
the pinned picture
- add `data-text` to a WhatsApp, Mastodon, Telegram, or Viber button to add
custom message text
- add `data-via` to a Twitter or Mastodon button to mention a user
- add `data-hashtags` to a Twitter or Facebook button to include hashtags in the shared post.
- Twitter supports multiple hashtags, and you need to specify them with out `#` and seperated with `,`, it shoule be something like this `ai,technologies,aigc`.
- Facebook only supports a single hashtag. If you pass multiple hashtags with `,` seperated, the library will only use the first one.
2020-03-25 19:44:31 -04:00
Here are all custom parameters:
2020-03-25 19:44:31 -04:00
```html
<div class="shareon" data-url="https://custom.url/for-this-page">
<a class="facebook" data-title="Custom Facebook title" data-hashtags="awesome"></a>
2022-02-08 12:56:39 -05:00
<a class="messenger" data-fb-app-id="0123456789012345"></a>
<a class="pinterest" data-media="https://custom.picture/for-pinterest">Pin</a>
2022-02-08 12:56:39 -05:00
<a class="telegram" data-text="Check this out!"></a>
<a class="twitter" data-via="MyNickname" data-hashtags="shareon,awesome,brilliant"></a>
2022-02-08 12:56:39 -05:00
<a class="mastodon" data-via="@MyNickname@myserver.social"></a>
<a class="whatsapp" data-url="https://custom.url/for-whatsapp">Send</a>
2020-03-25 11:32:25 -04:00
</div>
```
## Other versions
- [**WordPress plugin**](https://wordpress.org/plugins/shareon/) by [Gareth](https://github.com/gareth-gillman)
## Licence
2021-01-16 16:15:19 -05:00
Copyright © 20202022 [Nikita Karamov](https://www.kytta.dev/)
Licenced under the [MIT License](https://spdx.org/licenses/MIT.html).
Shareon was heavily inspired by [Likely](https://ilyabirman.net/likely/),
and has a somewhat backwards-compatible API (excluding themes and sizes).
Likely is licenced under the MIT License.
Shareon's logo is the
[Postal Horn emoji](https://github.com/googlefonts/noto-emoji/blob/43f47be9404018cd9d8f73a227363a8f20acdab5/svg/emoji_u1f4ef.svg)
from [Noto Emoji](https://github.com/googlefonts/noto-emoji).
Noto Emoji is licenced under the
[Apache License v2.0](https://github.com/googlefonts/noto-emoji/blob/43f47be9404018cd9d8f73a227363a8f20acdab5/LICENSE).
Share icons are being sourced from [Simple Icons](https://github.com/simple-icons/simple-icons/).
Simple Icons is released under [CC0](https://spdx.org/licenses/CC0-1.0.html),
but the icons themselves may be subject to copyright of the respective owners.
---
2021-01-16 17:50:16 -05:00
2023-01-23 00:06:31 -05:00
This project is hosted on GitHub: <https://github.com/kytta/shareon>