psammead-social-embed -

Description

The SocialEmbed component renders a rich social media embed for a number of supported providers or a fallback containing a link to the source content.

Supported providers

| Name | Value | | --------- | ----------- | | Instagram | instagram | | Twitter | twitter | | YouTube | youtube |

Installation

npm install @bbc/psammead-social-embed --save

Props

Canonical

| Argument | Type | Required | Default | Example | | ---------- | ------ | -------- | ------- | ------------------------------------------------------------------------------------------------------------------- | | provider | String | Yes | n/a | See supported providers. | | service | String | Yes | n/a | 'news' | | oEmbed | Object | Yes | n/a | See @bbc/psammead-oembed. | | fallback | Object | Yes | n/a | See fallback. | | skipLink | Object | Yes | n/a | See skipLink. | | caption | Object | No | null | See caption. | | onRender | Function | No | null | () => console.log('rendered') |

AMP

| Argument | Type | Required | Default | Example | | ---------- | ------ | -------- | ------- | ------------------------------------------------ | | provider | String | Yes | n/a | See supported providers. | | service | String | Yes | n/a | 'news' | | id | String | Yes | n/a | '1237210910835392512' | | fallback | Object | Yes | n/a | See fallback. | | skipLink | Object | Yes | n/a | See skipLink. | | caption | Object | No | null | See caption. |

fallback

| Argument | Type | Required | Default | Example | | ------------------------------ | ------ | -------- | ------- | ------------------------------------------------------------- | | text | String | Yes | n/a | "Sorry but we're having trouble displaying this content" | | linkText | String | Yes | n/a | 'View content on %provider_name%' | | linkTextSuffixVisuallyHidden | String | No | null | ', external' | | linkHref | String | Yes | n/a | 'https://twitter.com/MileyCyrus/status/1237210910835392512' | | warningText | String | No | null | Warning: BBC is not responsible for third party content |

skipLink

| Argument | Type | Required | Default | Example | | ----------------------- | ------ | -------- | ------- | ---------------------------------- | | text | String | Yes | n/a | 'Skip %provider_name% content' | | endTextId | String | Yes | n/a | 'skip-%provider%-content' | | endTextVisuallyHidden | String | Yes | n/a | 'End of %provider_name% content' |

caption

| Argument | Type | Required | Default | Example | | -------------------------- | ------ | -------- | ------- | ---------------------------------------------------- | | textPrefixVisuallyHidden | String | No | null | 'Video caption,' | | text | String | Yes | n/a | 'Warning: Third party content may contain adverts' |

See accessibility notes for more information.

Note: For your convenience, instances of %provider% and %provider_name% in fallback, skipLink and caption strings will be replaced with the current provider and, where the provider is known, the name of the provider. E.G. youtube and YouTube respectively.

Usage

Canonical

Pass a supported provider and valid oEmbed response. If neither of these cases can be met, a fallback will be rendered containing a link to the source content.

Example

import { CanonicalSocialEmbed } from '@bbc/psammead-social-embed';

<CanonicalSocialEmbed
  provider="instagram"
  service="news"
  oEmbed={{ html: '...' }}
  skipLink={{
    text: 'Skip %provider_name% content',
    endTextId: 'skip-%provider%-content',
    endTextVisuallyHidden: 'End of %provider_name% content',
  }}
  fallback={{
    text: "Sorry but we're having trouble displaying this content",
    linkText: 'View content on %provider_name%',
    linkTextSuffixVisuallyHidden: ', external',
    linkHref: 'https://www.instagram.com/p/B8FPf4ZphHi/',
    warningText: 'Warning: BBC is not responsible for third party content',
  }}
/>;

The component supports integration with the react-lazyload package ensuring the social media posts are rendered when they come into view.

Example

<LazyLoad height={200}>
  <CanonicalSocialEmbed provider="instagram" .../>
</LazyLoad>

onRender

This component takes an onRender prop which is invoked when the embed is fully rendered (currently only for twitter embeds), this can be used to change styling on render to help reduce layout shift.

Example

import React, { useState } from 'react';
import styled from '@emotion/styled';

const DEFAULT_MIN_HEIGHT = '18.75rem';

const Wrapper = styled.div`
  min-height: ${({ minHeight }) => minHeight};
`;

const SocialEmbedWithWrapper = ({
  provider,
  oEmbed,
  skipLink,
  fallback,
  service,
  }) => {

  const [wrapperMinHeight, setWrapperMinHeight] = useState(DEFAULT_MIN_HEIGHT);

  return (
    <Wrapper minHeight={wrapperMinHeight}>
      <CanonicalSocialEmbed
        provider={provider}
        oEmbed={oEmbed}
        skipLink={skipLink}
        fallback={fallback}
        service={service}
        onRender={() => {
          setMinHeight('0');
        }}
      />
    </Wrapper>
  );
};

export default SocialEmbedWithWrapper;

AMP

Pass a supported provider. If this case cannot be met, a fallback will be rendered containing a link to the source content.

Pass a valid id. This refers to the unique segment of the URL, which identifies the source content. E.G. 1237210910835392512 in https://twitter.com/MileyCyrus/status/1237210910835392512.

import { AmpSocialEmbed } from '@bbc/psammead-social-embed';

<AmpSocialEmbed
  provider="instagram"
  service="news"
  id="B8FPf4ZphHi"
  skipLink={{
    text: 'Skip %provider_name% content',
    endTextId: 'skip-%provider%-content',
    endTextVisuallyHidden: 'End of %provider_name% content',
  }}
  fallback={{
    text: "Sorry but we're having trouble displaying this content",
    linkText: 'View content on %provider_name%',
    linkTextSuffixVisuallyHidden: ', external',
    linkHref: 'https://www.instagram.com/p/B8FPf4ZphHi/',
    warningText: 'Warning: BBC is not responsible for third party content',
  }}
/>;

When to use this component

This component is designed to embed rich social media content from a number of supported providers in primary content, such as an article.

When not to use this component

This component will not provide a rich social media embed for providers outside of the supported providers – these will use fallback content instead.

Accessibility notes

This component provides a Skip Link, which allows users to identify and skip over social media content in your pages. skipLink.endTextId should be set to a value that uniquely identifies skipLink.endTextVisuallyHidden. This is especially important when there are more than one social media embeds from the same provider on a page.

fallback.linkTextSuffixVisuallyHidden is used to add a suffix to fallback.text. This will not be visible on the UI, but will be captured by assistive technology.

caption.textPrefixVisuallyHidden is used to add a prefix to caption.text. This will not be visible on the UI, but will be captured by assistive technology.

Miscellaneous

Some components within SocialEmbed render the same result given the same props and are memoized using React.memo to prevent unnecessary renders.

Contributing

Psammead is completely open source. We are grateful for any contributions, whether they be new components, bug fixes or general improvements. Please see our primary contributing guide which can be found at the root of the Psammead repository.

Code of Conduct

We welcome feedback and help on this work. By participating in this project, you agree to abide by the code of conduct. Please take a moment to read it.

License

Psammead is Apache 2.0 licensed.