BannerOverlay
Pilot

BannerOverlays displays short educational messages when users have performed actions that indicate some intent, such as a related pin tap or idea pin swipe. It is scrim-less, meaning users can scroll content underneath without having a wash layer on top of the content.

BannerOverlay is a sticky component triggered by scroll, on tap or long-press, placed at the bottom of the screen.

also known as UpsellOverlay

Figma:

Responsive:

Adaptive:

A11y:

Props

Component props
Name	Type	Default
`message` Required	`string \| React.Element<typeof Text>`	-
	Main content of BannerOverlay. Content should be localized. See the Text variant to learn more.
`offset`	`{ bottom: number, top: number }`	`"{ top: 0, bottom: 0 }"`
	Distance (in pixels) from the viewport edge (top will be used, if desktop, bottom will be used, if mobile).
`onDismiss`	`() => void`	-
	Adds a dismiss button to BannerOverlay. See the Dismissible variant for more info.
`primaryAction`	{ accessibilityLabel: string, href: string, label: string, onClick?: $ElementType<ElementConfig<typeof ButtonLink>, "onClick">, rel?: $ElementType<ElementConfig<typeof ButtonLink>, "rel">, role: "link", size?: $ElementType<ElementConfig<typeof ButtonLink>, "size">, target?: $ElementType<ElementConfig<typeof ButtonLink>, "target">, } \| { accessibilityLabel: string, label: string, onClick: $ElementType<ElementConfig<typeof Button>, "onClick">, role?: "button", size?: $ElementType<ElementConfig<typeof Button>, "size">, }	-
	Adds an optional primary button for user interaction. Main action for users to take on BannerOverlay. If href is supplied, the action will serve as a link. If no href is supplied, the action will be a button. The accessibilityLabel should follow the Accessibility guidelines. See the Primary action variant to learn more.
`secondaryAction`	{ accessibilityLabel: string, href: string, label: string, onClick?: $ElementType<ElementConfig<typeof ButtonLink>, "onClick">, rel?: $ElementType<ElementConfig<typeof ButtonLink>, "rel">, role: "link", size?: $ElementType<ElementConfig<typeof ButtonLink>, "size">, target?: $ElementType<ElementConfig<typeof ButtonLink>, "target">, } \| { accessibilityLabel: string, label: string, onClick: $ElementType<ElementConfig<typeof Button>, "onClick">, role?: "button", size?: $ElementType<ElementConfig<typeof Button>, "size">, }	-
	Adds an optional button for user interaction. In this case, we use our ButtonGroup component.
`thumbnail`	`{ image: React.Element<typeof Image> } \| { avatar: React.Element<typeof Avatar> } \| { icon: React.Element<typeof Icon> }`	-
	An optional thumbnail to display next to the text.
`title`	`string`	-
	Heading of BannerOverlay. Content should be localized. See the Text variant to learn more.
`zIndex`	`Indexable`	-
	zIndex of BannerOverlay. See the zIndex guidelines to learn more.

Usage guidelines

When to use

To provide short educational messages allowing content to scroll underneath
To help users learn more about a specific idea or interest
To support users when they have performed actions that indicate medium or high intent (related pin tap, idea pin swipe)

When not to use

If there is a need to block the content underneath use Modal instead
To replace Toast
For lengthy messages, forms, or blocks of information. Consider OverlayPanel or new page instead

Best Practices

Use BannerOverlay to educate and provide additional information to users when they have performed actions that indicate some intent, such as a related pin tap or idea pin swipe.

Don't

Use BannerOverlay for critical information, such as errors or warnings. Use BannerCallout instead.

Be concise when writing the content. The BannerOverlay is intended to display short messages. Ideally max of 3 lines.
Please consider localization.

Don't

Display long messages inside the BannerOverlay as it isn't the intent of this component, and it could lead to readability issues considering the component size and space.

Place BannerOverlay out of the way so a user can still navigate and complete tasks.

Please note: On desktop devices, the BannerOverlay should appear at the top of the screen (below navigation). The BannerOverlay shouldn't block navigation.
On mobile devices, the BannerOverlay should appear at the bottom of the screen. The 'offset' prop can be used to adjust the position of the BannerOverlay.

Don't

Stack multiple BannerOverlays; only one BannerOverlay should appear on the screen per time.

Accessibility

Not available

Labels

dismissButton and primaryAction, require a short, descriptive label for screen readers, which should also be localized.

Icons and thumbnails on BannerOverlay are purely decorative, and can therefore have an empty string as the accessibilityLabel. The thumbnail (Image) or Icon should supply an alt or accessibilityLabel, respectively, if the Image or Icon supplies extra context or information.

Variants

Remember to localize text and any string within primaryAction or dismissButton, as well as title and message.

Please note: Start aligned text is the primary alignment for our Business products. It will be left-aligned in left-to-right languages and right-aligned in right-to-left languages.

Image

import { useState } from 'react';
import { BannerOverlay, Button, FixedZIndex, Image, Link, Text } from 'gestalt';

export default function Example() {
  const [showComponent, setShowComponent] = useState(true);

  return !showComponent ? (
    <Button
      onClick={() => {
        setShowComponent(true);
      }}
      text="Show BannerOverlay"
    />
  ) : (
    <BannerOverlay
      message={
        <Text inline>
          Discover trending{' '}
          <Link display="inlineBlock" href="#" target="self">
            fashion
          </Link>{' '}
          ideas in the app!
        </Text>
      }
      offset={{ top: 130, bottom: 24 }}
      onDismiss={() => {
        setShowComponent(false);
      }}
      primaryAction={{
        role: 'button',
        onClick: () => {
          setShowComponent(false);
        },
        label: 'Get the app',
        accessibilityLabel: 'Get the app',
      }}
      thumbnail={{
        image: (
          <Image
            alt="Pinterest Logo"
            naturalHeight={1}
            naturalWidth={1}
            src="https://i.ibb.co/LQc8ynn/image.png"
          />
        ),
      }}
      title="More to Explore"
      zIndex={new FixedZIndex(100)}
    />
  );
}

With an image for Pin or Board actions, or the Pinterest logo.

Avatar

import { useState } from 'react';
import {
  Avatar,
  BannerOverlay,
  Button,
  FixedZIndex,
  Link,
  Text,
} from 'gestalt';

export default function Example() {
  const [showComponent, setShowComponent] = useState(true);

  return !showComponent ? (
    <Button
      onClick={() => {
        setShowComponent(true);
      }}
      text="Show BannerOverlay"
    />
  ) : (
    <BannerOverlay
      message={
        <Text inline>
          Discover trending{' '}
          <Link display="inlineBlock" href="#" target="self">
            fashion
          </Link>{' '}
          ideas in the app!
        </Text>
      }
      offset={{ top: 130, bottom: 24 }}
      onDismiss={() => {
        setShowComponent(false);
      }}
      primaryAction={{
        role: 'button',
        onClick: () => {
          setShowComponent(false);
        },
        label: 'Get the app',
        accessibilityLabel: 'Get the app',
      }}
      thumbnail={{
        avatar: (
          <Avatar name="Keerthi" src="https://i.ibb.co/ZfCZrY8/keerthi.jpg" />
        ),
      }}
      title="More to Explore"
      zIndex={new FixedZIndex(100)}
    />
  );
}

With an Avatar for Profile or Pinner-related messaging.

Icon

import { useState } from 'react';
import { BannerOverlay, Button, FixedZIndex, Icon, Link, Text } from 'gestalt';

export default function Example() {
  const [showComponent, setShowComponent] = useState(true);

  return !showComponent ? (
    <Button
      onClick={() => {
        setShowComponent(true);
      }}
      text="Show BannerOverlay"
    />
  ) : (
    <BannerOverlay
      message={
        <Text inline>
          Discover trending{' '}
          <Link display="inlineBlock" href="#" target="self">
            fashion
          </Link>{' '}
          ideas in the app!
        </Text>
      }
      offset={{ top: 130, bottom: 24 }}
      onDismiss={() => {
        setShowComponent(false);
      }}
      primaryAction={{
        role: 'button',
        onClick: () => {
          setShowComponent(false);
        },
        label: 'Get the app',
        accessibilityLabel: 'Get the app',
      }}
      thumbnail={{
        icon: (
          <Icon
            accessibilityLabel="Sparkle"
            color="recommendation"
            icon="sparkle"
          />
        ),
      }}
      title="More to Explore"
      zIndex={new FixedZIndex(100)}
    />
  );
}

For when an icon is needed to represent content that isn’t a pin or a profile.

Call to Action

import { useState } from 'react';
import { BannerOverlay, Button, FixedZIndex, Icon } from 'gestalt';

export default function Example() {
  const [showComponent, setShowComponent] = useState(true);

  return !showComponent ? (
    <Button
      onClick={() => {
        setShowComponent(true);
      }}
      text="Show BannerOverlay"
    />
  ) : (
    <BannerOverlay
      message="You can have up to two buttons in the BannerOverlay!"
      offset={{ top: 130, bottom: 24 }}
      onDismiss={() => {
        setShowComponent(false);
      }}
      primaryAction={{
        role: 'button',
        onClick: () => {
          setShowComponent(false);
        },
        label: 'Primary action',
        accessibilityLabel: 'Primary action',
      }}
      secondaryAction={{
        role: 'button',
        onClick: () => {},
        label: 'Secondary Action',
        accessibilityLabel: 'Secondary Action',
      }}
      thumbnail={{
        icon: (
          <Icon accessibilityLabel="Sparkle" color="info" icon="info-circle" />
        ),
      }}
      title="Call to Action"
      zIndex={new FixedZIndex(100)}
    />
  );
}

You can have zero, one or two actions using the props primaryAction and secondaryAction.

Dismissed by CTA

import { useState } from 'react';
import { BannerOverlay, Button, FixedZIndex, Icon } from 'gestalt';

export default function Example() {
  const [showComponent, setShowComponent] = useState(true);

  return !showComponent ? (
    <Button
      onClick={() => {
        setShowComponent(true);
      }}
      text="Show BannerOverlay"
    />
  ) : (
    <BannerOverlay
      message="You can dismiss this banner with the primary action!"
      offset={{ top: 130, bottom: 24 }}
      primaryAction={{
        role: 'button',
        onClick: () => {
          setShowComponent(false);
        },
        label: 'Got it!',
        accessibilityLabel: 'Got it!',
      }}
      thumbnail={{
        icon: (
          <Icon accessibilityLabel="Sparkle" color="info" icon="info-circle" />
        ),
      }}
      title="Dismissable Banner"
      zIndex={new FixedZIndex(100)}
    />
  );
}

You can optionally have the Call to Action dismiss the BannerOverlay by not setting the dismissButton prop.

Please note: Make sure to either set the CTA to dismiss the BannerOverlay or set the dismissButton prop. Otherwise, the BannerOverlay will be stuck on the screen.

Responsive

BannerOverlay is responsive to different devices. Therefore, BannerOverlay dweb is set to a max width of 900 px to preserve a great usability experience and consistency with other components.

On desktop devices, the BannerOverlay should appear at the top of the screen (below navigation). The BannerOverlay shouldn't block navigation.
On mobile devices, the BannerOverlay should appear at the bottom of the screen. The 'offset' prop can be used to adjust the position of the BannerOverlay.

Writing

Use succinct and scannable language that clearly conveys support to the user
Consider internationalization and how other languages may be constrained
Write up to 2 lines of text.

Don't

Write messages that are wordy and take up a lot of space, as the BannerOverlay is intended to short messages
Write content that takes more than 2 lines of text
Truncate content. If the message needs more words, consider a different component

BannerUpsell
BannerUpsell banners are used for paid upgrades, free trials, or marketing promotions.

Modal
A generic, customizable container for modals that aren’t used as alerts or acknowledgements and need more functionality like form fields.

Toast
Toasts educate users on the content of the screen, provide confirmation when people complete an action, or simply communicate a short message.

Edit page on GitHub

; Opens a new tab

BannerOverlay Pilot

also known as UpsellOverlay

Props

Usage guidelines

Best Practices

Accessibility

Labels

Variants

Image

Avatar

Icon

Call to Action

Dismissed by CTA

Responsive

Writing

Related

BannerOverlay
Pilot