An all-in-one React library to implement custom Sharing Meta and Social Media Sharing Buttons.
npm install @phntms/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.
Designed to use and extend OpenGraph standards, including built-in support for sharing with:
- Facebook
- Linkedin
- Twitter
- WhatsApp
- Copy to Clipboard
Install this package with npm.
``bash`
npm i @phntms/react-share
Example usage in Next.js:
`JSX
import Head from 'next/head';
import { MetaHeadEmbed } from "@phntms/react-share";
const PageLayout: React.FC = ({children}) => {
<>
export default PageLayout;
`
| 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. |Home
| pageTitle | string | No | Unique page title that describes the page, such as , About etc. etc. |pageTitle
| siteTitle | string | Yes | Title of the site, usually the organization / brand name. If and siteTitle are the same, only this shows. |pageTitle
| titleTemplate | string | No | Title template used to display and siteTitle in a template, displays the values using corresponding [pageTitle] and [siteTitle]. Example template: "[pageTitle] | [siteTitle]". |false
| 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 . |"your, tags"
| keywords | string|string[] | No | List of SEO keywords describing what your webpage does. Example, or ["your", "tags"]. |baseSiteUrl
| 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, is prefixed. If specifying a relative URL do not add the leading slash. |1200
| imageAlt | string | No | Image alt for users who are visually impaired. |
| imageWidth | number | No | Width of share image, defaults to . |630
| imageHeight | number | No | Height of share image, defaults to . |en_GB
| locale | string | No | The locale these tags are marked up in, such as; , 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.
| 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).small
- For 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.
| 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;
`
| 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;
`
| 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"]. |"your, tags"
| related | string|string[] | No | Accounts to recommend following. Example, or ["your", "tags"]. |
Basic component example usage:
`jsx
import { getTwitterUrl } from "@phntms/react-share";
const ShareToTwitter = () => (
Share to Twitter
);
export default ShareToTwitter;
`
| 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!
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;
`
Method used to copy a given text into your clipboard.
`jsx
import { copyToClipboard } from "@phntms/react-share";
const Copy = () => (
export default Copy;
`
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.
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