AMP

Important: this documentation is not applicable to your currently selected format stories!

amp-social-share

 
You can now use this component outside valid AMP documents using the Bento version of this component. Learn more in the Bento guide.

Description

Usage

 

Required Scripts

<script async custom-element="amp-social-share" src="https://cdn.ampproject.org/v0/amp-social-share-0.1.js"></script>

Usage

The amp-social-share component displays a social share button for social platforms.

Currently, none of the buttons generated by amp-social-share (including those for the pre-configured providers) have a label/accessible name that is exposed to assistive technologies (such as screen readers). Make sure to include an aria-label with a descriptive label, as otherwise these controls will just be announced as unlabelled "button" elements.

Example: Basic social share button

The share button guesses some defaults for you for some pre-configured providers. It assumes that the current document canonical url is the URL you want to share and the page title is the text you want to share.

<amp-social-share
  type="twitter"
  aria-label="Share on Twitter"
></amp-social-share>

Example: Passing parameters

When you want to pass parameters to the share endpoint, you can specify data-param-<attribute> that will be appended to the share endpoint.

<amp-social-share
  type="linkedin"
  width="60"
  height="44"
  data-param-text="Hello world"
  data-param-url="https://example.com/"
  aria-label="Share on LinkedIn"
>
</amp-social-share>

Linkedin is one of the pre-configured providers, so you do not need to provide the data-share-endpoint attribute.

Pre-configured providers

The amp-social-share component provides some pre-configured providers that know their sharing endpoints as well as some default parameters.

Provider Type Parameters
Web Share API (triggers OS share dialog) system
  • data-param-text: optional, defaults to: "Current page title"
  • data-mode: optional, if set to replace, all other share options are removed.
Email email
  • data-param-subject: optional, defaults to: Current page title
  • data-param-body: optional, defaults to: rel=canonical URL
  • data-param-recipient: optional, defaults to: '' (empty string)
Facebook facebook
  • data-param-app_id: required, defaults to: none. This parameter is the Facebook app_id that's required for the Facebook Share dialog.
  • data-param-href: optional, defaults to: rel=canonical URL
  • data-param-quote: optional. Can be used to share a quote or text.
LinkedIn linkedin
  • data-param-url: optional, defaults to: rel=canonical URL
Pinterest pinterest
  • data-param-media: optional (but highly recommended to be set), defaults to: none. Url for the media to be shared on Pinterest. If not set, the end user will be requested to upload a media by Pinterest.
  • data-param-url: optional, defaults to: rel=canonical URL
  • data-param-description: optional, defaults to: Current page title
Tumblr tumblr
  • data-param-url: optional, defaults to: rel=canonical URL
  • data-param-text: optional, defaults to: Current page title
Twitter twitter
  • data-param-url: optional, defaults to: rel=canonical URL
  • data-param-text: optional, defaults to: Current page title
Whatsapp whatsapp
  • data-param-text: optional, defaults to: "Current page title - current page URL"
LINE line
  • data-param-url: optional, defaults to: rel=canonical URL
  • data-param-text: optional, defaults to: Current page title
SMS sms
  • data-param-body: optional, defaults to: rel=title - rel=canonical URL

Non-configured providers

In addition to pre-configured providers, you can use non-configured providers by specifying additional attributes in the amp-social-share component.

Example: Creating a share button for a non-configured provider

The following example creates a share button through Facebook Messenger by setting the data-share-endpoint attribute to the correct endpoint for the Facebook Messenger custom protocol.

<amp-social-share
  type="facebookmessenger"
  data-share-endpoint="fb-messenger://share"
  data-param-text="Check out this article: TITLE - CANONICAL_URL"
  aria-label="Share on Facebook Messenger"
>
</amp-social-share>

As these providers are not pre-configured, you'll need to create the appropriate button image and styles for the provider.

Variable Substitution

You can use global AMP variables substitution in the <amp-social-share> element. In the example below, TITLE is substituted with the page title and CANONICAL_URL with the document's canonical URL.

<amp-social-share
  type="whatsapp"
  data-param-text="Check out this article: TITLE - CANONICAL_URL"
>
</amp-social-share>

Attributes

type (required)

Selects a provider type. This is required for both pre-configured and non-configured providers.

data-target

Specifies the target in which to open the target. The default is _blank for all cases other than email/SMS on iOS, in which case the target is set to _top.

Please note that we only suggest using this override for email.

data-share-endpoint

This attribute is required for non-configured providers.

Some popular providers have pre-configured share endpoints. For details, see the Pre-configured Providers section. For non-configured providers, you'll need to specify the share endpoint.

data-param-*

All data-param-* prefixed attributes are turned into URL parameters and passed to the share endpoint.

aria-label

By default, the aria-label attribute will be populated with Share by type where 'type' is the type attribute provided to the component. If a non-empty value is passed in to aria-label it will overwrite the default value.

Styling

Default Styles

By default, amp-social-share includes some popular pre-configured providers. Buttons for these providers are styled with the provider's official color and logo. The default width is 60px, and the default height is 44px.

Visit AMP Start for responsive, pre-styled share links that you can use in your AMP pages.

Custom Styles

Sometimes you want to provide your own style. You can simply override the provided styles like the following:

amp-social-share[type='twitter'] {
  background: red;
  background-image: url(datauri:svg/myownsvgicon);
}

When customizing the style of an amp-social-share icon please ensure that the customized icon meets the branding guidelines set out by the provider (e.g Twitter, Facebook, etc.)

Accessibility

Indication of focus

The amp-social-share element defaults to a blue outline as a visible focus indicator. It also defaults tabindex=0 making it easy for a user to follow along as he or she tabs through multiple amp-social-share elements used together on a page.

The default focus indicator is achieved with the following CSS rule-set.

amp-social-share:focus {
  outline: #0389ff solid 2px;
  outline-offset: 2px;
}

The default focus indicator can be overwritten by defining CSS styles for focus and including them within a style tag on an AMP HTML page. In the example below, the first CSS rule-set removes the focus indicator on all amp-social-share elements by setting the outline property to none. The second rule-set specifies a red outline (instead of the default blue) and also sets the outline-offset to be 3px for all amp-social-share elements with the class custom-focus.

amp-social-share:focus{
  outline: none;
}

amp-social-share.custom-focus:focus {
  outline: red solid 2px;
  outline-offset: 3px;
}

With these CSS rules, amp-social-share elements would not show the visible focus indicator unless they included the class custom-focus in which case they would have the red outlined indicator.

Color contrast

Note that amp-social-share with a type value of twitter, whatsapp, or line will display a button with a foreground/background color combination that falls below the 3:1 threshold recommended for non-text content defined in WCAG 2.1 SC 1.4.11 Non-text Contrast.

Without sufficient contrast, content can be difficult to perceive and therefore difficult to identify. In extreme cases, content with low contrast may not be visible at all to people with colour perception impairments. In the case of the above share buttons, users may not be able to appropriately perceive/understand what the share controls are, what service they relate to.

Validation

See amp-social-share rules in the AMP validator specification.

Need more help?

You've read this document a dozen times but it doesn't really cover all of your questions? Maybe other people felt the same: reach out to them on Stack Overflow.

Go to Stack Overflow
Found a bug or missing a feature?

The AMP project strongly encourages your participation and contributions! We hope you'll become an ongoing participant in our open source community but we also welcome one-off contributions for the issues you're particularly passionate about.

Go to GitHub