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:
importHeadfrom'next/head';import{MetaHeadEmbed}from"@phntms/react-share";constPageLayout: React.FC=({children})=>{<><MetaHeadEmbedrender={(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}</>);exportdefaultPageLayout;| 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";constShareToFacebook=()=>(<ahref={getFacebookUrl({url: "https://phantom.land/"})}>
Share to Facebook
</a>);exportdefaultShareToFacebook;| 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";constShareToLinkedin=()=>(<ahref={getLinkedinUrl({url: "https://phantom.land/"})}>
Share to Linkedin
</a>);exportdefaultShareToLinkedin;| 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";constShareToTwitter=()=>(<ahref={getTwitterUrl({url: "https://phantom.land/"})}>Share to Twitter</a>);exportdefaultShareToTwitter;| 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";constShareToWhatsApp=()=>(<ahref={getWhatsAppUrl({url: "https://phantom.land/"})}>
Share to WhatsApp
</a>);exportdefaultShareToWhatsApp;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";constShare=()=>(<ahref={getShareUrl(SocialPlatforms.Facebook,{url: "https://phantom.land/"})}>
Share to Facebook
</a><ahref={getShareUrl(SocialPlatforms.Linkedin,{url: "https://phantom.land/"})}>SharetoLinkedin</a><ahref={getShareUrl(SocialPlatforms.Twitter,{url: "https://phantom.land/"})}>
Share to Twitter
</a><ahref={getShareUrl(SocialPlatforms.WhatsApp,{url: "https://phantom.land/"})}>SharetoWhatsApp</a>);exportdefaultShare;Method used to copy a given text into your clipboard.
import{copyToClipboard}from"@phntms/react-share";constCopy=()=>(<divonClick={()=>copyToClipboard("https://phantom.land")}>Copy</div>);exportdefaultCopy;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!