❤
npm
Sign UpSign In

This package has been deprecated

Author message:

See @bentoproject/social-share

@ampproject/amp-social-share

1.2110011758.0 • Public • Published

Bento Social Share

Usage

The Bento Social Share component displays a social share button for social platforms.

Currently, none of the buttons generated by Bento Social Share (including those for the pre-configured providers) have a label or 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.

Web Component

You must include each Bento component's required CSS library to guarantee proper loading and before adding custom styles. Or use the light-weight pre-upgrade styles available inline. See Layout and style.

The examples below demonstrate use of the <bento-social-share> web component.

Example: Import via npm

[example preview="top-frame" playground="false"]

Install via npm:

npm install @ampproject/bento-social-share
import '@ampproject/bento-social-share';

[/example]

Example: Include via <script>

[example preview="top-frame" playground="false"]

<head>
  <!-- These styles prevent Cumulative Layout Shift on the unupgraded custom element -->
  <style data-bento-boilerplate>
    bento-social-share {
      display: inline-block;
      overflow: hidden;
      position: relative;
      box-sizing: border-box;
      width: 60px;
      height: 44px;
    }
  </style>
  <script async src="https://cdn.ampproject.org/v0/bento-twitter-1.0.js"></script>
  <style>
    bento-social-share {
      width: 375px;
      height: 472px;
    }
  </style>
</head>

<bento-social-share id="my-share"
  type="twitter"
  aria-label="Share on Twitter"
></bento-social-share>

<div class="buttons" style="margin-top: 8px;">
  <button id="change-share">
    Change share button
  </button>
</div>

<script>
  (async () => {
    const button = document.querySelector('#my-share');
    await customElements.whenDefined('bento-social-share');

    // set up button actions
    document.querySelector('#change-share').onclick = () => {
      twitter.setAttribute('type', 'linkedin')
      twitter.setAttribute('aria-label', 'Share on LinkedIn')
    }
  })();
</script>

[/example]

Layout and style

Each Bento component has a small CSS library you must include to guarantee proper loading without content shifts. Because of order-based specificity, you must manually ensure that stylesheets are included before any custom styles.

<link rel="stylesheet" type="text/css" href="https://cdn.ampproject.org/v0/amp-social-share-1.0.css">

Alternatively, you may also make the light-weight pre-upgrade styles available inline:

<style data-bento-boilerplate>
  bento-social-share {
    display: inline-block;
    overflow: hidden;
    position: relative;
    box-sizing: border-box;
    width: 60px;
    height: 44px;
  }
</style>

Container type

The bento-social-share component has a defined layout size type. To ensure the component renders correctly, be sure to apply a size to the component and its immediate children (slides) via a desired CSS layout (such as one defined with height, width, aspect-ratio, or other such properties):

bento-social-share {
  height: 100px;
  width: 100px;
}
Default Styles

By default, bento-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.

Custom Styles

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

bento-social-share[type='twitter'] {
  color: blue;
  background: red;
}

When customizing the style of an bento-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 bento-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 they tab through multiple bento-social-share elements used together on a page.

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

bento-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. In the example below, the first CSS rule-set removes the focus indicator on all bento-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 bento-social-share elements with the class custom-focus.

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

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

With these CSS rules, bento-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 bento-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.

Pre-configured providers

The bento-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
Email email
  • data-param-subject: optional
  • data-param-body: optional
  • data-param-recipient: optional
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
  • data-param-quote: optional, can be used to share a quote or text.
LinkedIn linkedin
  • data-param-url: optional
Pinterest pinterest
  • data-param-media: optional (but highly recommended to be set). 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
  • data-param-description: optional
Tumblr tumblr
  • data-param-url: optional
  • data-param-text: optional
Twitter twitter
  • data-param-url: optional
  • data-param-text: optional
Whatsapp whatsapp
  • data-param-text: optional
LINE line
  • data-param-url: optional
  • data-param-text: optional
SMS sms
  • data-param-body: optional

Non-configured providers

In addition to pre-configured providers, you can use non-configured providers by specifying additional attributes in the bento-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.

<bento-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"
>
</bento-social-share>

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

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.

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

The description of the button for accessibility. A recommended label is "Share on <type>".

Preact/React Component

The examples below demonstrate use of the <BentoSocialShare> as a functional component usable with the Preact or React libraries.

Example: Import via npm

[example preview="top-frame" playground="false"]

Install via npm:

npm install @ampproject/bento-social-share
import React from 'react';
import { BentoSocialShare } from '@ampproject/bento-social-share/react';
import '@ampproject/bento-social-share/styles.css';

function App() {
  return (
    <BentoSocialShare
      type="twitter"
      aria-label="Share on Twitter"
    ></BentoSocialShare>
  );
}

[/example]

Layout and style

Container type

The BentoSocialShare component has a defined layout size type. To ensure the component renders correctly, be sure to apply a size to the component and its immediate children (slides) via a desired CSS layout (such as one defined with height, width, aspect-ratio, or other such properties). These can be applied inline:

<BentoSocialShare
  style={{width: 50, height: 50}}
  type="twitter"
  aria-label="Share on Twitter"
></BentoSocialShare>

Or via className:

<BentoSocialShare
  className="custom-styles"
  type="twitter"
  aria-label="Share on Twitter"
></BentoSocialShare>
.custom-styles {
  height: 50px;
  width: 50px;
}

Accessibility

Indication of focus

The BentoSocialShare 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 BentoSocialShare elements used together on a page.

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

BentoSocialShare: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 BentoSocialShare 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 BentoSocialShare elements with the class custom-focus.

BentoSocialShare:focus{
  outline: none;
}

BentoSocialShare.custom-focus:focus {
  outline: red solid 2px;
  outline-offset: 3px;
}

With these CSS rules, BentoSocialShare 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 BentoSocialShare 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.

Pre-configured providers

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

Provider Type Parameters via param prop
Web Share API (triggers OS share dialog) system
  • text: optional
Email email
  • subject: optional
  • body: optional
  • recipient: optional
Facebook facebook
  • app_id: required, defaults to: none. This parameter is the Facebook app_id that's required for the Facebook Share dialog.
  • href: optional
  • quote: optional, can be used to share a quote or text.
LinkedIn linkedin
  • url: optional
Pinterest pinterest
  • media: optional (but highly recommended to be set). Url for the media to be shared on Pinterest. If not set, the end user will be requested to upload a media by Pinterest.
  • url: optional
  • description: optional
Tumblr tumblr
  • url: optional
  • text: optional
Twitter twitter
  • url: optional
  • text: optional
Whatsapp whatsapp
  • text: optional
LINE line
  • url: optional
  • text: optional
SMS sms
  • body: optional

Non-configured providers

In addition to pre-configured providers, you can use non-configured providers by specifying additional attributes in the BentoSocialShare 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.

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

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

Props

type (required)

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

background

Sometimes you want to provide your own style. You can simply override the provided styles by giving a color for the background.

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

color

Sometimes you want to provide your own style. You can simply override the provided styles by giving a color for the fill.

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

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.

endpoint

This prop 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.

params

All param properties are passed as URL parameters and passed to the share endpoint.

aria-label

The description of the button for accessibility. A recommended label is "Share on <type>".

Readme

Keywords

none

Package Sidebar

Install

npm i @ampproject/amp-social-share

Repository

github.com/ampproject/amphtml

Homepage

github.com/ampproject/amphtml/tree/main/extensions/amp-social-share/1.0

Weekly Downloads

1

Version

1.2110011758.0

License

Apache-2.0

Unpacked Size

725 kB

Total Files

20

Last publish

Collaborators

  • alanorozco
  • amp-toolbox
  • ampproject-admin
  • ampprojectbot
  • caroqliu
  • choumx
  • dvoytenko
  • erwinmombay
  • esth
  • fstanis
  • jridgewell
  • kdwan
  • kristoferbaxter
  • patrickkettner
  • rsimha
  • samouri
Try on RunKit
Report malware