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:
- Copy to Clipboard
Install this package with npm.
npm i @phntms/react-shareExample usage in Next.js:
import Head from 'next/head'; import { MetaHeadEmbed } from "@phntms/react-share"; const PageLayout: React.FC = ({children}) => { <> <MetaHeadEmbed render={(meta: React.ReactNode) => <Head>{meta}</Head>} 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;| 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. |
| 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
largecards, use a 2:1 aspect ratio (300x157 px minium or 4096x4096 px maximum). - For
smallcards, 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:
import { getFacebookUrl } from "@phntms/react-share"; const ShareToFacebook = () => ( <a href={getFacebookUrl({ url: "https://phantom.land/" })}> Share to Facebook </a> ); 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:
import { getLinkedinUrl } from "@phntms/react-share"; const ShareToLinkedin = () => ( <a href={getLinkedinUrl({ url: "https://phantom.land/" })}> Share to Linkedin </a> ); 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"]. |
| related | string|string[] | No | Accounts to recommend following. Example, "your, tags" or ["your", "tags"]. |
Basic component example usage:
import { getTwitterUrl } from "@phntms/react-share"; const ShareToTwitter = () => ( <a href={getTwitterUrl({ url: "https://phantom.land/" })}>Share to Twitter</a> ); 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:
import { getWhatsAppUrl } from "@phntms/react-share"; const ShareToWhatsApp = () => ( <a href={getWhatsAppUrl({ url: "https://phantom.land/" })}> Share to WhatsApp </a> ); 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:
import { getShareUrl, SocialPlatforms } from "@phntms/react-share"; const Share = () => ( <a href={getShareUrl(SocialPlatforms.Facebook, {url: "https://phantom.land/" })}> Share to Facebook </a> <a href={getShareUrl(SocialPlatforms.Linkedin, { url: "https://phantom.land/" })}> Share to Linkedin </a> <a href={getShareUrl(SocialPlatforms.Twitter, { url: "https://phantom.land/" })}> Share to Twitter </a> <a href={getShareUrl(SocialPlatforms.WhatsApp, { url: "https://phantom.land/" })}> Share to WhatsApp </a> ); export default Share;Method used to copy a given text into your clipboard.
import { copyToClipboard } from "@phntms/react-share"; const Copy = () => ( <div onClick={() => copyToClipboard("https://phantom.land")}>Copy</div> ); 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!