react-share

[![NPM version][npm-image]][npm-url]
[![Actions Status][ci-image]][ci-url]
[![PR Welcome][npm-downloads-image]][npm-downloads-url]

An all-in-one React library to implement custom Page Sharing Meta and Social Media Sharing Buttons.

Introduction

Designed to use and extend OpenGraph standards, including built-in support for sharing with:

- Facebook
- Linkedin
- Twitter
- WhatsApp
- Copy to Clipboard

Installation

Install this package with npm.

``bash
npm i @phntms/react-share
`

Usage

Example usage in Next.js:

`JSX
import Head from 'next/head';
import { MetaHeadEmbed } from "@phntms/react-share";

const PageLayout: React.FC = ({children}) => {
<>
render={(meta: React.ReactNode) => {meta}}
siteTitle="PHANTOM"
pageTitle="Our Work"
titleTemplate="[pageTitle] | [siteTitle]"
description="Transforming challenges of all shapes and sizes into inventive, engaging and performance driven solutions that change the game."
baseSiteUrl="https://phantom.land"
pagePath="work"
keywords={["creative-agency", "phantom", "work"]}
imageUrl="https://bit.ly/3wiUOuk"
imageAlt="PHANTOM logo."
twitter={{
cardSize: "large",
siteUsername: "@phntmLDN",
creatorUsername: "@phntmLDN",
}}
/>
{children}

);

export default PageLayout;
`

$3

| Property | Type | Required | Notes |
| -------------------- | -------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| render | React.ReactNode | Yes | Unfortunately react-helmet and next/head are strict with how they accept meta tags. react-helmet doesn't support nesting. Whereas Next.JS only supports some children and not all, therefore a render function is required. |
| pageTitle | string | No | Unique page title that describes the page, such as Home, About etc. etc. |
| siteTitle | string | Yes | Title of the site, usually the organization / brand name. If pageTitle and siteTitle are the same, only this shows. |
| titleTemplate | string | No | Title template used to display pageTitle and siteTitle in a template, displays the values using corresponding [pageTitle] and [siteTitle]. Example template: "[pageTitle] | [siteTitle]". |
| description | string | Yes | A one to two sentence description of your webpage. Keep it within 160 characters, and write it to catch the user's attention. |
| baseSiteUrl | string | Yes | Base site URL, excluding trailing slash. |
| pagePath | string | No | The path of the current page, excluding leading slash. |
| disableCanonical | boolean | No | Disable canonical if not desired, defaults to false. |
| keywords | string|string[] | No | List of SEO keywords describing what your webpage does. Example, "your, tags" or ["your", "tags"]. |
| imageUrl | string | No | Image url of asset to share. Recommended aspect ratio for landscape is 1.9:1 (1200x630) or for squares 1:1 (1200x1200). For more info, visit here. If a relative URL is provided, baseSiteUrl is prefixed. If specifying a relative URL do not add the leading slash. |
| imageAlt | string | No | Image alt for users who are visually impaired. |
| imageWidth | number | No | Width of share image, defaults to 1200. |
| imageHeight | number | No | Height of share image, defaults to 630. |
| locale | string | No | The locale these tags are marked up in, such as; en_GB, fr_FR and es_ES. Defaults to en_US. |
| twitter | TwitterEmbedProps | No | Optional twitter embed properties to include. |

To use simply add MetaHeadEmbed to a shared layout to get the best out of page specific properties such as pagePath.

Note: baseSiteUrl and imageUrl must start with https://, else they won't work when sharing.

$3

| Property | Type | Required | Notes |
| ------------------- | -------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| cardSize | 'small'|'large' | Yes | Summary card size. |
| title | string | No | A concise title for the related content. If left blank, page title will be inherited instead. |
| description | string | No | A description that concisely summarizes the content as appropriate for presentation within a Tweet. Should not be the same as title. If left blank, MetaHeadEmbed description will be inherited instead. |
| siteUsername | string | No | The Twitter @username the card should be attributed to. |
| creatorUsername | string | No | The Twitter @username for the content creator / author. |
| imageUrl | string | No | Image to show in card. Images must be less than 5MB in size. Supported file types; JPG, PNG, WEBP and GIF. |
| imageAlt | string | No | Image alt for users who are visually impaired. Maximum 420 characters. |

Note: Image used should be different based on cardSize:

- For large cards, use a 2:1 aspect ratio (300x157 px minium or 4096x4096 px maximum).
- For small cards, use a 1:1 aspect ratio (144x144 px minium or 4096x4096 px maximum).

A Note on Twitter Tags

Twitter will inherit og:title, og:description and og:image tags by default, so unless you want unique fields, respective fields in TwitterEmbedProps should be left blank to avoid duplication.

$3

| Parameter | Type | Required | Notes |
| --------- | ------ | -------- | --------------------------------- |
| url | string | Yes | URL of shared webpage. |
| hashtag | string | No | Hashtag to show in Facebook card. |

Basic component example usage:

`jsx
import { getFacebookUrl } from "@phntms/react-share";

const ShareToFacebook = () => (

Share to Facebook

);

export default ShareToFacebook;
`

$3

| Parameter | Type | Required | Notes |
| --------- | ------ | -------- | --------------------------------------------------------------------- |
| url | string | Yes | URL of shared webpage. |
| title | string | No | Title to show in card. |
| summary | string | No | Description to show in card. |
| source | string | No | Source of the content. For example, your website or application name. |

Basic component example usage:

`jsx
import { getLinkedinUrl } from "@phntms/react-share";

const ShareToLinkedin = () => (

Share to Linkedin

);

export default ShareToLinkedin;
`

$3

| Parameter | Type | Required | Notes |
| --------- | -------------------- | -------- | ------------------------------------------------------------------------------- |
| url | string | Yes | URL of shared webpage. |
| text | string | No | Text to show in Twitter card. |
| hashtags | string|string[] | No | Hashtags to show in Twitter card. Example, "your,tags" or ["your", "tags"]. |
| related | string|string[] | No | Accounts to recommend following. Example, "your, tags" or ["your", "tags"]. |

Basic component example usage:

`jsx
import { getTwitterUrl } from "@phntms/react-share";

const ShareToTwitter = () => (
Share to Twitter
);

export default ShareToTwitter;
`

$3

| Parameter | Type | Required | Notes |
| --------- | ------ | -------- | ---------------------------------------------------- |
| url | string | Yes | URL of shared webpage. |
| text | string | No | Text to show in the WhatsApp message before the URL. |

Basic component example usage:

`jsx
import { getWhatsAppUrl } from "@phntms/react-share";

const ShareToWhatsApp = () => (

Share to WhatsApp

);

export default ShareToWhatsApp;
`

Note: WhatsApp links will only work on mobile, so be sure to hide any WhatsApp links if the user is not on a mobile device!

$3

If you would rather have all share urls in one place, getShareUrl() can be used! It includes props from every social platform listed above, so simply pass in a SocialPlatform, and the platforms corresponding props.

Example usage:

`jsx
import { getShareUrl, SocialPlatforms } from "@phntms/react-share";

const Share = () => (

Share to Facebook


Share to Linkedin


Share to Twitter


Share to WhatsApp

);

export default Share;
`

$3

Method used to copy a given text into your clipboard.

`jsx
import { copyToClipboard } from "@phntms/react-share";

const Copy = () => (


export default Copy;
`

Further Resources

Useful resources for testing meta properties:

- Meta Tags - With Meta Tags you can preview how your webpage will look on Google, Facebook, Twitter and more.
- Social Share Preview - Chrome browser extension to live preview how the webpage will look when shared. Especially useful for testing when app is auth protected.

🍰 Requests and Contributing

If a social media platform you want to use isn't already supported, or found an issue? Get involved! Please contribute using the GitHub Flow. Create a branch, add commits, and open a Pull Request or submit a new issue.

Please read CONTRIBUTING for details on our CODE_OF_CONDUCT`, and the process for submitting pull requests to us!

[npm-image]: https://img.shields.io/npm/v/@phntms/react-share.svg?style=flat-square&logo=react
[npm-url]: https://npmjs.org/package/@phntms/react-share
[npm-downloads-image]: https://img.shields.io/npm/dm/@phntms/react-share.svg
[npm-downloads-url]: https://npmcharts.com/compare/@phntms/react-share?minimal=true
[ci-image]: https://github.com/phantomstudios/react-share/workflows/test/badge.svg
[ci-url]: https://github.com/phantomstudios/react-share/actions