Upsell

View source on GitHub

Upsells are banners that display short messages that focus on promoting an action or upgrading something the user already has.

⚠️ Please note: Upsell is not currently supported in dark mode.

Give $30, get $60 in ads credit

Earn $60 of ads credit, and give $30 of ads credit to a friend

Send invite

Upsell Props

Name	Type	Default
`message` Required	`string`	-
	Main content of Upsell, explains what is being offered or recommended. Content should be localized. See Best Practices for more info.
`children`	`typeof Upsell.Form`	-
	To create forms within Upsell, pass Upsell.Form as children
`dismissButton`	`{\| accessibilityLabel: string, onDismiss: () => void, \|}`	-
	Adds a dismiss button to the Upsell. The `accessibilityLabel` should follow the Accessibility guidelines
`imageData`	`{\| component: typeof Image \| typeof Icon, width?: number, mask: { rounding: "circle" \| 0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 7 \| 8, wash: boolean} \|}`	-
	Either an Icon or an Image to render at the start of the banner. Width is not used with Icon. Image width defaults to 128px. See the Icon and Image variants for more info.
`primaryAction`	`{\| accessibilityLabel: string, disabled?: boolean, href?: string, label: string, onClick?: AbstractEventHandler<\| SyntheticMouseEvent<HTMLButtonElement> \| SyntheticMouseEvent<HTMLAnchorElement> \| SyntheticKeyboardEvent<HTMLAnchorElement> \| SyntheticKeyboardEvent<HTMLButtonElement>, {\| dangerouslyDisableOnNavigation: () => void \|}`	-
	Main action for people to take on Upsell. If `href` is supplied, the action will serve as a link. See OnLinkNavigationProvider to learn more about link navigation.' If no `href` is supplied, the action will be a button. The `accessibilityLabel` should follow the Accessibility guidelines.
`secondaryAction`	`{\| accessibilityLabel: string, disabled?: boolean, href?: string, label: string, onClick?: AbstractEventHandler<\| SyntheticMouseEvent<HTMLButtonElement> \| SyntheticMouseEvent<HTMLAnchorElement> \| SyntheticKeyboardEvent<HTMLAnchorElement> \| SyntheticKeyboardEvent<HTMLButtonElement>, {\| dangerouslyDisableOnNavigation: () => void \|}`	-
	Secondary action for people to take on Upsell. If `href` is supplied, the action will serve as a link. See OnLinkNavigationProvider to learn more about link navigation.' If no `href` is supplied, the action will be a button. The `accessibilityLabel` should follow the Accessibility guidelines.
`title`	`string`	-
	Brief title summarizing the Upsell. Content should be localized.

Upsell.Form Props

Name	Type	Default
`children` Required	`React.Node`	-
	Contents of the form, typically inputs like TextField(s).
`onSubmit` Required	`({\| event: SyntheticMouseEvent<HTMLButtonElement> \| SyntheticKeyboardEvent<HTMLButtonElement> \| SyntheticMouseEvent<HTMLAnchorElement> \| SyntheticKeyboardEvent<HTMLAnchorElement> \|}) => void`	-
	Actions to perform when the form has been submitted.
`submitButtonAccessibilityLabel` Required	`string`	-
	Label for the submit button used for screen readers. Should follow the Accessibility guidelines.
`submitButtonText` Required	`string`	-
	Content of the submit button.
`submitButtonDisabled`	`boolean`	-
	Disables the submit button when `true`.

Usage guidelines

When to Use

Displaying promotional information to a user that is not tied to a task or state on the surface.
Sharing updates or changes to the features and offerings of the product.

When Not to Use

Anything related to state or status within the surface. Consider a Callout instead.
Promoting or highlighting specific elements / areas within a surface. Let the team know if this is needed.

Best practices

Give $30, get $60 in ads credit

Earn $60 of ads credit, and give $30 of ads credit to a friend

Send invite

Use Upsells for marketing new products or encouraging upgrades.

Give $30, get $60 in ads credit

Earn $60 of ads credit, and give $30 of ads credit to a friend

Send invite

Place Upsell at the top of the page under the primary navigation when possible.

First Upsell:

Measure ad performance

Install the Pinterest tag to track your website traffic, conversions and more.

Follow-up Upsell:

So close! Finish installing your Pinterest tag, get $10 in ads credit

Track ads conversion—sales, traffic and more—with the Pinterest tag

Plan for the timing of your Upsells with new product launches. Try to create different messages for each time an Upsell appears to the user.

Could not link account

There was a problem connecting your account.

Don't

Use Upsells for critical information, such as errors or warnings. Use Callout instead. Upsells should not be used for general information either.

So close! Finish installing your Pinterest tag, get $10 in ads credit

Track ads conversion—sales, traffic and more—with the Pinterest tag

Give $30, get $60 in ads credit

Earn $60 of ads credit, and give $30 of ads credit to a friend

Send invite

Don't

Stack Upsells on a page. In the case that they must be stacked, Callouts will appear above Upsells.

Measure ad performance

Install the Pinterest tag to track your website traffic, conversions and more.

Measure ad performance

Install the Pinterest tag to track your website traffic, conversions and more.

Don't

Keep showing the same Upsell once it has been dismissed. Upsells should only appear a maximum of 2 times to the same user, as they have diminishing returns.

Accessibility

Labels

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

In the case of action Buttons or Links, alternative text should be provided through the accessibilityLabel prop to replace vague text like "Visit" or "Learn more" with more descriptive information, like "Learn more about work from home resources". Avoid using the words "button" or "link" in the label, as this becomes repetitive. If the action text is already descriptive, an empty string can be passed.

For the dismissButton IconButton, the label provided should indicate the intent, like “Dismiss this banner”.

The Image or Icon supplied to imageData should only supply an alt or accessibilityLabel, respectively, if the Image or Icon supplies extra context or information. Icons in Upsells are often purely decorative, and can therefore have an empty string as the accessibilityLabel.

Give $30, get $60 in ads credit

Earn $60 of ads credit, and give $30 of ads credit to a friend

Send invite

<Upsell
  dismissButton={{
    accessibilityLabel: 'Dismiss banner',
    onDismiss: () => {},
  }}
  imageData={{
    component: <Icon icon="pinterest" accessibilityLabel="" color="darkGray" size={32} />,
  }}
  message="Earn $60 of ads credit, and give $30 of ads credit to a friend"
  primaryAction={{
    href: 'https://pinterest.com',
    label: 'Send invite',
    accessibilityLabel: 'Invite friend to use ads',
    target: 'blank',
  }}
  title="Give $30, get $60 in ads credit"
/>;

<Upsell
  dismissButton={{
    accessibilityLabel: 'Dismiss banner',
    onDismiss: () => {},
  }}
  imageData={{
    component: <Icon icon="pinterest" accessibilityLabel="" color="darkGray" size={32} />,
  }}
  message="Earn $60 of ads credit, and give $30 of ads credit to a friend"
  primaryAction={{
    href: 'https://pinterest.com',
    label: 'Send invite',
    accessibilityLabel: 'Invite friend to use ads',
    target: 'blank',
  }}
  title="Give $30, get $60 in ads credit"
/>;

Localization

Remember to localize all link or button labels, as well as title and message.

Fast fertig! Beenden Sie die Installation Ihres Pinterest-Tags und erhalten Sie ein Guthaben von 10 Euro

Verfolgen Sie die Anzeigenkonvertierung - Umsatz, Traffic und mehr - mit dem Pinterest Tag

<Upsell
  imageData={{
    component: <Icon icon="send" accessibilityLabel="" color="darkGray" size={32} />,
  }}
  message="Verfolgen Sie die Anzeigenkonvertierung - Umsatz, Traffic und mehr - mit dem Pinterest Tag"
  primaryAction={{
    label: 'Beanspruche jetzt',
    accessibilityLabel: 'Beanspruche Guthaben jetzt',
    target: 'blank',
  }}
  title="Fast fertig! Beenden Sie die Installation Ihres Pinterest-Tags und erhalten Sie ein Guthaben von 10 Euro"
/>;

<Upsell
  imageData={{
    component: <Icon icon="send" accessibilityLabel="" color="darkGray" size={32} />,
  }}
  message="Verfolgen Sie die Anzeigenkonvertierung - Umsatz, Traffic und mehr - mit dem Pinterest Tag"
  primaryAction={{
    label: 'Beanspruche jetzt',
    accessibilityLabel: 'Beanspruche Guthaben jetzt',
    target: 'blank',
  }}
  title="Fast fertig! Beenden Sie die Installation Ihres Pinterest-Tags und erhalten Sie ein Guthaben von 10 Euro"
/>;

Variants

Text-only

Used to convey a short message that requires no action, except dismiss.

Single line Upsell with no title or call to action.

<Upsell
  dismissButton={{
    accessibilityLabel: 'Dismiss this banner',
    onDismiss: () => {},
  }}
  message="Single line Upsell with no title or call to action."
/>;

<Upsell
  dismissButton={{
    accessibilityLabel: 'Dismiss this banner',
    onDismiss: () => {},
  }}
  message="Single line Upsell with no title or call to action."
/>;

Icon

The Icon is used to add additional meaning to the Upsell. The icon can reference a Pinterest product, feature or an action from our Icon library.

Give $30, get $60 in ads credit

Earn $60 of ads credit, and give $30 of ads credit to a friend

Send invite

<Upsell
  dismissButton={{
    accessibilityLabel: 'Dismiss banner',
    onDismiss: () => {},
  }}
  imageData={{
    component: <Icon icon="pinterest" accessibilityLabel="" color="darkGray" size={32} />,
  }}
  message="Earn $60 of ads credit, and give $30 of ads credit to a friend"
  primaryAction={{
    href: 'https://pinterest.com',
    label: 'Send invite',
    accessibilityLabel: 'Invite friend to use ads',
    target: 'blank',
  }}
  title="Give $30, get $60 in ads credit"
/>;

<Upsell
  dismissButton={{
    accessibilityLabel: 'Dismiss banner',
    onDismiss: () => {},
  }}
  imageData={{
    component: <Icon icon="pinterest" accessibilityLabel="" color="darkGray" size={32} />,
  }}
  message="Earn $60 of ads credit, and give $30 of ads credit to a friend"
  primaryAction={{
    href: 'https://pinterest.com',
    label: 'Send invite',
    accessibilityLabel: 'Invite friend to use ads',
    target: 'blank',
  }}
  title="Give $30, get $60 in ads credit"
/>;

Image

The Image in Upsell is used to add visual interest and draw the user’s attention. Images should relate to the message of the Upsell. Upsell images should use approved photography or be illustrations using our brand colors. Images will always be 128px wide.

Stay healthy and safe

Check out our resources for adapting to these times.

Visit

<Upsell
  dismissButton={{
    accessibilityLabel: 'Dismiss banner',
    onDismiss: () => {},
  }}
  imageData={{
    component: (
      <Image
        alt=""
        color="rgb(231, 186, 176)"
        naturalHeight={751}
        naturalWidth={564}
        src="https://i.ibb.co/7bQQYkX/stock2.jpg"
      />
    ),
    mask: { rounding: 4 },
    width: 128,
  }}
  message="Check out our resources for adapting to these times."
  primaryAction={{
    href: 'https://pinterest.com',
    label: 'Visit',
    accessibilityLabel: 'Visit our Stay Safe resources',
    target: 'blank',
  }}
  title="Stay healthy and safe"
/>;

<Upsell
  dismissButton={{
    accessibilityLabel: 'Dismiss banner',
    onDismiss: () => {},
  }}
  imageData={{
    component: (
      <Image
        alt=""
        color="rgb(231, 186, 176)"
        naturalHeight={751}
        naturalWidth={564}
        src="https://i.ibb.co/7bQQYkX/stock2.jpg"
      />
    ),
    mask: { rounding: 4 },
    width: 128,
  }}
  message="Check out our resources for adapting to these times."
  primaryAction={{
    href: 'https://pinterest.com',
    label: 'Visit',
    accessibilityLabel: 'Visit our Stay Safe resources',
    target: 'blank',
  }}
  title="Stay healthy and safe"
/>;

Actions

Upsells can have either one primary action, or a primary action and a secondary action. These actions can be buttons, when no href is supplied, or links, by specifying the href property.

Upsell actions with link interaction can be paired with OnLinkNavigationProvider. See OnLinkNavigationProvider to learn more about link navigation.

For example, “Learn more” may link to a separate documentation site, while “Send invite” could be a button that opens a Modal with an invite flow. Be sure to localize the labels of the actions.

If needed, actions can become disabled after clicking by setting disabled: true in the action data.

Give $30, get $60 in ads credit

Earn $60 of ads credit, and give $30 of ads credit to a friend

Learn more

function Example(props) {
  const [showModal, setShowModal] = React.useState(false);

  return (
    <Box marginStart={-1} marginEnd={-1}>
      <Upsell
        dismissButton={{
          accessibilityLabel: 'Dismiss banner',
          onDismiss: () => {},
        }}
        message="Earn $60 of ads credit, and give $30 of ads credit to a friend"
        primaryAction={{
          accessibilityLabel: 'Send ads invite',
          label: 'Send invite',
          onClick: () => {
            setShowModal(!showModal);
          },
        }}
        secondaryAction={{
          accessibilityLabel: 'Learn more: Verified Merchant Program',
          href: 'https://help.pinterest.com/en/business/article/verified-merchant-program',
          label: 'Learn more',
          target: 'blank',
        }}
        title="Give $30, get $60 in ads credit"
      />

      {showModal && (
        <Layer>
          <Modal
            accessibilityModalLabel="Invite a friend to the Verified Merchant Program"
            footer={
              <Flex flex="grow" justifyContent="end">
                <ButtonGroup>
                  <Button
                    onClick={() => {
                      setShowModal(!showModal);
                    }}
                    size="lg"
                    text="Cancel"
                  />
                  <Button color="red" size="lg" text="Send invite" />
                </ButtonGroup>
              </Flex>
            }
            heading="Verified Merchant Program Invitation"
            onDismiss={() => {
              setShowModal(!showModal);
            }}
            size="md"
            subHeading="When your friend spends their first $30 on ads, you’ll earn $60 of ads credit, and they’ll get $30 of ads credit, too."
          >
            <Flex direction="row">
              <Column span={12}>
                <Box display="flex" paddingY={2} paddingX={8}>
                  <Column span={4}>
                    <Label htmlFor="name">
                      <Text align="left" weight="bold">
                        Friend's Name
                      </Text>
                    </Label>
                  </Column>

                  <Column span={8}>
                    <TextField id="name" onChange={() => undefined} />
                  </Column>
                </Box>

                <Box display="flex" paddingY={2} paddingX={8}>
                  <Column span={4}>
                    <Label htmlFor="email">
                      <Text align="left" weight="bold">
                        Friend's E-mail
                      </Text>
                    </Label>
                  </Column>

                  <Column span={8}>
                    <TextField id="email" onChange={() => undefined} />
                  </Column>
                </Box>

                <Box display="flex" paddingY={2} paddingX={8}>
                  <Column span={4}>
                    <Label htmlFor="desc">
                      <Text align="left" weight="bold">
                        Personal Message
                      </Text>
                    </Label>
                  </Column>

                  <Column span={8}>
                    <TextArea id="desc" onChange={() => undefined} />
                  </Column>
                </Box>
              </Column>
            </Flex>
          </Modal>
        </Layer>
      )}
    </Box>
  );
}

function Example(props) {
  const [showModal, setShowModal] = React.useState(false);
  return (
    <Box marginStart={-1} marginEnd={-1}>
      <Upsell
        dismissButton={{
          accessibilityLabel: 'Dismiss banner',
          onDismiss: () => {},
        }}
        message="Earn $60 of ads credit, and give $30 of ads credit to a friend"
        primaryAction={{
          accessibilityLabel: 'Send ads invite',
          label: 'Send invite',
          onClick: () => {
            setShowModal(!showModal);
          },
        }}
        secondaryAction={{
          accessibilityLabel: 'Learn more: Verified Merchant Program',
          href: 'https://help.pinterest.com/en/business/article/verified-merchant-program',
          label: 'Learn more',
          target: 'blank',
        }}
        title="Give $30, get $60 in ads credit"
      />
      {showModal && (
        <Layer>
          <Modal
            accessibilityModalLabel="Invite a friend to the Verified Merchant Program"
            footer={
              <Flex flex="grow" justifyContent="end">
                <ButtonGroup>
                  <Button
                    onClick={() => {
                      setShowModal(!showModal);
                    }}
                    size="lg"
                    text="Cancel"
                  />
                  <Button color="red" size="lg" text="Send invite" />
                </ButtonGroup>
              </Flex>
            }
            heading="Verified Merchant Program Invitation"
            onDismiss={() => {
              setShowModal(!showModal);
            }}
            size="md"
            subHeading="When your friend spends their first $30 on ads, you’ll earn $60 of ads credit, and they’ll get $30 of ads credit, too."
          >
            <Flex direction="row">
              <Column span={12}>
                <Box display="flex" paddingY={2} paddingX={8}>
                  <Column span={4}>
                    <Label htmlFor="name">
                      <Text align="left" weight="bold">
                        Friend's Name
                      </Text>
                    </Label>
                  </Column>
                  <Column span={8}>
                    <TextField id="name" onChange={() => undefined} />
                  </Column>
                </Box>
                <Box display="flex" paddingY={2} paddingX={8}>
                  <Column span={4}>
                    <Label htmlFor="email">
                      <Text align="left" weight="bold">
                        Friend's E-mail
                      </Text>
                    </Label>
                  </Column>
                  <Column span={8}>
                    <TextField id="email" onChange={() => undefined} />
                  </Column>
                </Box>
                <Box display="flex" paddingY={2} paddingX={8}>
                  <Column span={4}>
                    <Label htmlFor="desc">
                      <Text align="left" weight="bold">
                        Personal Message
                      </Text>
                    </Label>
                  </Column>
                  <Column span={8}>
                    <TextArea id="desc" onChange={() => undefined} />
                  </Column>
                </Box>
              </Column>
            </Flex>
          </Modal>
        </Layer>
      )}
    </Box>
  );
}

Forms

Inputs can be added to Upsells to collect information from users (ex: name or email) through the use of Upsell.Form. Most Upsells should have no more than 2 inputs. If more inputs are needed, direct users to a full page using the primaryAction.

Single TextField

Give $30, get $60 in ads credit

Earn $60 of ads credit, and give $30 of ads credit to a friend

function FormExample(props) {
  const [value, setValue] = React.useState('');
  const handleSubmit = ({ event }) => {
    event.preventDefault();
    // your submit logic using state values
  };

  return (
    <Upsell
      dismissButton={{
        accessibilityLabel: 'Dismiss banner',
        onDismiss: ()=>{},
      }}
      imageData={{
        component: <Icon icon="pinterest" accessibilityLabel="Pin" color="darkGray" size={32}/>
      }}
      message="Earn $60 of ads credit, and give $30 of ads credit to a friend"
      title="Give $30, get $60 in ads credit"
    >
      <Upsell.Form
        onSubmit={handleSubmit}
        submitButtonAccessibilityLabel="Submit name for ads credit"
        submitButtonText="Submit"
      >
        <TextField
          id="nameField"
          onChange={({ value }) => setValue(value)}
          placeholder="Name"
          value={value}
        />
      </Upsell.Form>
    </Upsell>
  );
}

function FormExample(props) {
  const [value, setValue] = React.useState('');
  const handleSubmit = ({ event }) => {
    event.preventDefault();
    // your submit logic using state values
  };
  return (
    <Upsell
      dismissButton={{
        accessibilityLabel: 'Dismiss banner',
        onDismiss: ()=>{},
      }}
      imageData={{
        component: <Icon icon="pinterest" accessibilityLabel="Pin" color="darkGray" size={32}/>
      }}
      message="Earn $60 of ads credit, and give $30 of ads credit to a friend"
      title="Give $30, get $60 in ads credit"
    >
      <Upsell.Form
        onSubmit={handleSubmit}
        submitButtonAccessibilityLabel="Submit name for ads credit"
        submitButtonText="Submit"
      >
        <TextField
          id="nameField"
          onChange={({ value }) => setValue(value)}
          placeholder="Name"
          value={value}
        />
      </Upsell.Form>
    </Upsell>
  );
}

Multiple TextFields

Interested in a free ads consultation?

Learn how to grow your business with a Pinterest ads expert today!

function Example(props) {
  const [nameValue, setNameValue] = React.useState('');
  const [emailValue, setEmailValue] = React.useState('');
  const handleSubmit = ({ event }) => {
    event.preventDefault();
    // your submit logic using state values
  };

  return (
    <Upsell
      dismissButton={{
        accessibilityLabel: 'Dismiss banner',
        onDismiss: () => {},
      }}
      imageData={{
        component:
          <Image
            alt="Succulent plant against pink background"
            color="rgb(231, 186, 176)"
            naturalHeight={751}
            naturalWidth={564}
            src="https://i.ibb.co/7bQQYkX/stock2.jpg"
          />,
          mask: {rounding: 4},
        width: 128,
      }}
      message="Learn how to grow your business with a Pinterest ads expert today!"
      title="Interested in a free ads consultation?"
    >
      <Upsell.Form
        onSubmit={handleSubmit}
        submitButtonAccessibilityLabel="Submit info for contact"
        submitButtonText="Contact me"
      >
        <Box display="block" smDisplay="flex">
          <Box
            flex="grow"
            smMarginEnd={1}
            marginEnd={0}
            smMarginBottom={0}
            marginBottom={2}
          >
            <TextField
              id="name"
              onChange={({ value }) => setNameValue(value)}
              placeholder="Name"
              value={nameValue}
            />
          </Box>

          <Box flex="grow" smMarginStart={1} marginStart={0}>
            <TextField
              id="email"
              onChange={({ value }) => setEmailValue(value)}
              placeholder="Email"
              type="email"
              value={emailValue}
            />
          </Box>
        </Box>
      </Upsell.Form>
    </Upsell>
  );
}

function Example(props) {
  const [nameValue, setNameValue] = React.useState('');
  const [emailValue, setEmailValue] = React.useState('');
  const handleSubmit = ({ event }) => {
    event.preventDefault();
    // your submit logic using state values
  };
  return (
    <Upsell
      dismissButton={{
        accessibilityLabel: 'Dismiss banner',
        onDismiss: () => {},
      }}
      imageData={{
        component:
          <Image
            alt="Succulent plant against pink background"
            color="rgb(231, 186, 176)"
            naturalHeight={751}
            naturalWidth={564}
            src="https://i.ibb.co/7bQQYkX/stock2.jpg"
          />,
          mask: {rounding: 4},
        width: 128,
      }}
      message="Learn how to grow your business with a Pinterest ads expert today!"
      title="Interested in a free ads consultation?"
    >
      <Upsell.Form
        onSubmit={handleSubmit}
        submitButtonAccessibilityLabel="Submit info for contact"
        submitButtonText="Contact me"
      >
        <Box display="block" smDisplay="flex">
          <Box
            flex="grow"
            smMarginEnd={1}
            marginEnd={0}
            smMarginBottom={0}
            marginBottom={2}
          >
            <TextField
              id="name"
              onChange={({ value }) => setNameValue(value)}
              placeholder="Name"
              value={nameValue}
            />
          </Box>
          <Box flex="grow" smMarginStart={1} marginStart={0}>
            <TextField
              id="email"
              onChange={({ value }) => setEmailValue(value)}
              placeholder="Email"
              type="email"
              value={emailValue}
            />
          </Box>
        </Box>
      </Upsell.Form>
    </Upsell>
  );
}

Callout
Use Callout when communicating critical information, such as an error or warning. Callout can also be used to present the user with general information and further actions they can take, like the successful creation of a business account.

Toast
Toast provides feedback on a user interaction, like a confirmation that appears when a Pin has been saved. Unlike Upsell and Callout, Toasts don’t contain actions. They’re also less persistent, and disappear after a certain duration.

OnLinkNavigationProvider
OnLinkNavigationProvider allows external link navigation control across all children components with link behavior.

ActivationCard
ActivationCards are used in groups to communicate a user’s stage in a series of steps toward an overall action.

Edit page on GitHub

Upsell

Upsell Props

Upsell.Form Props

Usage guidelines

Best practices

Accessibility

Labels

Localization

Variants

Text-only

Icon

Image

Actions

Forms

Related