Skip to content

Developer Platform

Search docs & API
Log in
Sign up

Buttons

Save Button

The Save button is the best way for your business to get content on Pinterest. With just one click, visitors can save content they like on your site to Pinterest, which helps even more Pinners discover you.
As of 11 October 2018 we rolled out sticky Save buttons that work on mobile devices when hovering Save buttons are enabled on the page.
As of 11 October 2018 we rolled out sticky Save buttons that work on mobile devices when hovering Save buttons are enabled on the page.
  1. To turn sticky Save buttons off, add
    data-pin-sticky="false"
    to your call to
    pinit.js
    .

Getting started

First, make sure you've included the
pinit.js
script on your page. Remember, you only need to include this once per page, no matter how many Pinterest widgets you use. See Add ons overview for tips about how best to include our JavaScript on your site.
pinit.js script:
<script type="text/javascript" async defer src="//assets.pinterest.com/js/pinit.js"></script>
To add a Save button to your page, insert this code where you want your button to go:
<a href="https://www.pinterest.com/pin/create/button/" data-pin-do="buttonBookmark"> </a>

Button settings

Button settings control how your Save button looks and acts. There are four categories of settings:
  • Pin type settings: Pin type settings control what content Pinners can save from your page
  • Button style settings: Button style settings control how your button looks
  • Source settings: Source settings control canonical sources, including descriptions, urls and images
  • Log settings: Log settings control how errors and logging are handled

Pin type settings

Pin type props
AttributeDescriptionValuesDefault
data-pin-do
Determines whether the Pinner can save any image from the page (all images will appear in the Image Picker form) or is restricted to saving a particular image (and is taken straight to the Pin Create form).
buttonBookmark
(any image) or
buttonPin
(one image) If you use
buttonPin
, you have to specify an image URL using the
media
attribute. Other optional attributes include the
url
and
description
attributes, which specify the Pin URL and the Pin’s description.
buttonBookmark
data-pin-id
If you’ve already saved this image, use this attribute to treat any new Pins of this image as repins of the original. Doing this can give you a better feel for engagement, because any Pins you create will count towards repins of your original Pin. This attribute is applied individually to images on your page.
The Pin URL[not set] (new Pin)
data-pin-nopin
The image can't be saved, and hover buttons won't appear on the image. This attribute is applied to individual images on your page.
[any value] or [blank] If you pass in any value, nobody can Pin the image.
[not set]

Button style settings

Button style props
AttributeDescriptionValuesDefault
data-pin-hover
Shows the Save button only when a user hovers over images. This applies to all images on the page. Add this attribute to your call to pinit.js.
[any value] or [not set] If you pass in any value, the Save button will appear on hover for all images on the page, unless the image includes the
data-pin-nopin
 or
data-pin-no-hover
 attribute.
No hover ([not set])
data-pin-sticky
Sticky buttons are on by default when
data-pin-hover="true"
. This setting turns them off. Add this attribute to your call to pinit.js.
[false] If you pass in
false
when
data-pin-hover
is set, sticky Save buttons will not appear on mobile devices.
[not set]
data-pin-round
Changes the Save button to the round and red style. This overrides the
data-pin-color
and
data-pin-count
attributes (round buttons won’t show Pin counts). Add this attribute to your call to pinit.js to change all buttons on your page, or add this attribute to a single image to change the button only for that image.
true
or [not set] (for rectangle)		rectangle ([not set])
data-pin-tall
Changes the height of the Save button. Rectangular buttons are twice as wide as they are tall. Add this attribute to your call to pinit.js to change all buttons on your page, or add this attribute to a single image to change the button only for that image.
Rectangular buttons:
true
(28px for rectangular, 32px for round) or [not set] (20px for rectangular, 16px for round)
[Not set]
data-pin-count
Shows the Pin count for one-image (
data-pin-do="buttonPin"
) Save buttons. Note: Pin counts won't appear for round, hover or custom buttons. Add this attribute to your call to
pinit.js
to change all buttons on your page, or add this attribute to a single image to change the button only for that image.
above
beside
or not shown		[Not set]
data-pin-custom
If you set this, we won't touch any custom HTML or CSS you add for the button. Using a custom image will override all other button style attributes. Make sure that your custom Save buttons follow our brand guidelines. See custom buttons for more information about using custom Save buttons. Add this attribute to your call to pinit.js to change all buttons on your page, or add this attribute to a single image to change the button only for that image.
true
or [not set]		[not set]

Source settings

Source props
AttributeDescriptionValuesDefault
data-pin-description
Overrides the default image description and substitutes an image description you provide. You can include up to 500 characters, but only 75-100 will appear in grid view. For tips on using descriptions, see best practices. This attribute is added individually to images on your page.
User-defined descriptionPage title
data-pin-media
Overrides the image and substitutes a different image in the Pin Create form. For tips on using media, see best practices. This attribute is added individually to images on your page.
Image URLOriginal source image
data-pin-url
Overrides the image's page URL and substitutes the URL of your choice. This attribute is added individually to images on your page.
URLURL of the page where the image is
data-pin-no-hover
Hover buttons won't appear over this image, but the image can still be saved unless the
data-pin-nopin
 attribute is set. This attribute is added individually to images on your page.
[any value] or [not set] If you pass in any value, hover buttons won't appear on the image.
[not set]

Log settings

Log props
AttributeDescriptionValuesDefault
data-pin-error
Logs all build and interaction events to the console. Add this attribute to your call to pinit.js.
[any value] or [not set][not set]
data-pin-error
The name of the function you want us to call if one of our API endpoints replies with an error. You have to build this yourself. It would be useful in combination with
data-pin-build
if you’re dynamically creating board widgets.
User defined[not set]
data-pin-tag
Creates a logging tag for analytics. Tags may include the characters a-z, A-Z, 0-9 and underscore, and are constrained to 32 characters.
User defined[not set]

Examples

Default Save Button

  • This will open the image picker form and let the user save any image on the page.
  • You can restrict users to saving the image you specify with the
    data-pin-do="buttonPin"
    attribute.
  • data-pin-save="true"
    sets the Pin button to the current style. Note that the default is
    true
    so if this value is not set, the current style will be used.
<a data-pin-do="buttonBookmark" href="https://www.pinterest.com/pin/create/button/"> </a>

Round Save Button

Turn your button round using the
data-pin-shape="round"
attribute. In addition, you can use the following:
  • data-pin-do="buttonPin"
    limits the user to pinning the specific image given.
  • data-pin-round="true"
    sets the Pin button shape to
    round
  • data-pin-save="false"
    sets the Pin button to the old "Pin It" style. (Not recommended for non-English sites.)
  • href="https://www.pinterest.com/pin/create/button/?url=URLofImageToPin&description=DescriptionOfImage"
    indicates the URL and description of the specific image the user is able to Pin
  • <img src="//assets.pinterest.com/images/pidgets/pinit_fg_en_round_red_16.png" />
    defines the image to be used for the button
<a
  data-pin-do="buttonPin"
  href="https://www.pinterest.com/pin/create/button/?url=http://www.foodiecrush.com/2014/03/filet-mignon-with-porcini-mushroom-compound-butter/&media=https://i.pinimg.com/736x/17/34/8e/17348e163a3212c06e61c41c4b22b87a.jpg&description=So%20delicious!"
  data-pin-shape="round"
>
</a>

Large Save Button

Turn your button large using the
data-pin-tall="true"
attribute.
  • data-pin-do="buttonPin"
    limits the user to pinning the specific image given.
  • data-pin-tall="true"
    doubles the size of the button compared to the standard
  • data-pin-save="true"
    This is the default value, and will use the current Pin button styling
  • href="https://www.pinterest.com/pin/create/button/?url=URLofImageToPin&description=DescriptionOfImage"
    inidicates the URL and description of the specific image the user is able to Pin
<a
  data-pin-do="buttonPin"
  data-pin-tall="true"
  data-pin-save="true"
  href="https://www.pinterest.com/pin/create/button/?url=http://www.foodiecrush.com/2014/03/filet-mignon-with-porcini-mushroom-compound-butter/&media=https://i.pinimg.com/736x/17/34/8e/17348e163a3212c06e61c41c4b22b87a.jpg&description=So%20delicious!"
  data-pin-height="28"
>
</a>

Default Save Button with save count listed above

Get this look by using the
data-pin-count="above"
attribute.
<a
  data-pin-do="buttonPin"
  data-pin-count="above"
  data-pin-save="true"
  href="https://www.pinterest.com/pin/create/button/?url=http://www.foodiecrush.com/2014/03/filet-mignon-with-porcini-mushroom-compound-butter/&media=https://i.pinimg.com/736x/17/34/8e/17348e163a3212c06e61c41c4b22b87a.jpg&description=So%20delicious!"
  data-pin-config="above"
>
</a>

Default Save Button with save count listed to the side

Get this look by using the
data-pin-count="beside"
attribute.
<a
  data-pin-do="buttonPin"
  data-pin-count="beside"
  data-pin-save="true"
  href="https://www.pinterest.com/pin/create/button/?url=http://www.foodiecrush.com/2014/03/filet-mignon-with-porcini-mushroom-compound-butter/&media=https://i.pinimg.com/736x/17/34/8e/17348e163a3212c06e61c41c4b22b87a.jpg&description=So%20delicious!"
  data-pin-config="beside"
>
</a>

Custom Save Button with a user-provided image

This uses the
data-pin-custom="true"
attribute.
<a
  data-pin-do="buttonPin"
  data-pin-count="beside"
  data-pin-custom="true"
  data-pin-save="false"
  href="https://www.pinterest.com/pin/create/button/?url=http://www.foodiecrush.com/2014/03/filet-mignon-with-porcini-mushroom-compound-butter/&media=https://i.pinimg.com/736x/17/34/8e/17348e163a3212c06e61c41c4b22b87a.jpg&description=So%20delicious!"
  data-pin-custom="true"
>
  <img
    src="https://addons.opera.com/media/extensions/55/19155/1.1-rev1/icons/icon_64x64.png"
    width="25"
    height="25"
  />
</a>

Custom button conversion

If you've been using a custom ("unofficial") Save button (that doesn't use pinit.js), you've been missing out on automatic updates, analytics, technical support from our team and smarter recommendations for your users. You can convert your old Pin It buttons to an official Save button easily and without losing any of your customizations.
The steps to convert your buttons to "official" will depend on whether you created them using HTML or JavaScript. Either way, make sure you've included pinit.js on your page (and make sure you've only included it once).
<script async defer src="//assets.pinterest.com/js/pinit.js"></script>

If you're using HTML

You only need to add two attributes to your anchor tag to make it official:
  • data-pin-do="<PIN_TYPE>"
  • data-pin-custom="true"
With PIN_TYPE:
The PIN_TYPE can be either
  • buttonPin
    (allowing the user to Pin only this specific image)
  • buttonBookmark
    (allowing the user to Pin any image on your page)
To allow the user to Pin only this specific image, use
data-pin-do="buttonPin"
. To allow the user to Pin any image on your page, use
data-pin-do="buttonBookmark"
With custom:
Setting data-pin-custom to
true
keeps your custom markup, including your HTML and CSS. The value of
data-pin-custom
defaults to
false
so if this attribute isn't included we will render a standard Save buttons instead.
Example of a custom button with HTML
<a
  href="https://www.pinterest.com/pin/create/button/"
  data-pin-do="buttonBookmark"
  data-pin-custom="true"
>
  --YOUR CUSTOM HTML--
</a>

If you're using JavaScript

If you're using your own JavaScript to open the Pin Create form, switch to using the helper utilities that come with
pinit.js
. Including
pinit.js
gives you a global variable, PinUtils, that can trigger the any-image grid, Pin Create form or repin form.
PinUtils functions
FunctionDescription
PinUtils.pinAny();
Takes no arguments. This function opens the Image Picker form and lets the Pinner save any image from your page.
PinUtils.pinOne(<PIN>);
This function opens the Pin Create form and restricts the user to saving an image you have chosen from your site. Three fields are available to pass in
<PIN>
:
  • media
    (required): the url of the image you want to save.
  • url
    (optional): the url that the Pin will link to. This defaults to the url the user saves the Pin from.
  • description
    (optional): the Pin's description. This defaults to the document title.
Example:
PinUtils.pinOne({
'url': 'https://www.flickr.com/photos/kentbrew/6851/',
'media': 'https://farm8.staticflickr.com/7027/68517.jpg',
'description': 'Next stop: Pinterest!'
});
PinUtils.repin('<PIN_ID>');
This function links to an already existing Pin rather than creating a new Pin. It requires an existing Pin id.
Example:
PinUtils.repin('99360735500167749');
PinUtils.pinOne() example Javascript:
PinUtils.pinOne
  (
    {
      url: 'https://www.flickr.com/photos/kentbrew/6851/',
      media: 'https://farm8.staticflickr.com/7027/68517.jpg',
      description: 'Next stop: Pinterest!'
    }
  );`
If you want to change the name of the global function to something besides PinUtils, set
data-pin-util="<YOUR_VAR_NAME>"
in your your call to pinit.js.
Example:
<button
  class="social pinterest"
  data-media="http://tinyurl.com/p3rqf54"
  data-description="A delicious burger"
></button>
<script>
  var pinOneButton = document.querySelector('.pinterest');
  pinOneButton.addEventListener('click', function () {
    PinUtils.pinOne({
      media: e.target.getAttribute('data-media'),
      description: e.target.getAttribute('data-description'),
    });
  });
</script>

Best practices

The Save button is one of the best ways to get your content onto Pinterest through visitors to your site. Make sure your Save button is doing the most for you by following our best practices.
  • Include pinit.js correctly. Make sure you've included our JavaScript and that it is only included once per page. If you don't call pinit.js, your buttons and widgets won't render. If you call pinit.js more than once, unpredictable results will occur, especially if you are using global configuration attributes.
  • Use the Save button that's best for your website. We offer a lot of different style options for the Save button, so make sure you are using the one that will benefit you the most. Here are some suggestions for which kind to use, depending on what kind of content you have on your site:
  • Multiple images on a page (like a blog): it's best to use the hover button. When somebody hovers over any image on the page, the Save button will appear.
  • Multiple, similar images (like a product page): use the one-image Save button. This button specifies a single image to Pin from the page, no matter how many images are present.
  • Images that have already been saved before: consider using the data-pin-id attribute to create a repin (instead of a new Pin) every time someone saves content from your page. This can help you gain a better feel for engagement. Plus, you can get email notifications about who's saving content from your site.
  • An active mobile site: remember that hover buttons are not supported on mobile. Use a one-image or any-image button instead.

Check your images

Since Pinterest is entirely image-based, it's important that your images are correctly formatted and look their best.
Images need to be at least 100px by 200px to be saved to Pinterest by the Save button, and 200px by 200px to be saved using the hover button. Make sure at least one image is loaded outside of an iframe on your page. The Save button can't find images inside of iframes.
Use the
data-pin-media
attribute to provide a better-quality version of the image if you have one. Images with text overlays, tasteful branding and vertical orientation perform best on Pinterest. You can use the
data-pin-media
attribute to make these types of images available from the Save button

Prefill your descriptions

Use the
data-pin-description
attribute to pre-fill your Pin descriptions. Using prefilled descriptions lets users save content from your site faster, and can increase visibility of your Pin on Pinterest because it has an accurate description. If you don't specify a description, we'll pull descriptions from your page's alt or title tags, which may not be accurate for every image on the page.
When writing your descriptions, remember the following:
  • Descriptions can be up to 500 characters. While only 75-100 characters of your description will appear in grid view, the entire description will appear when Pinners click on a Pin.
  • Generally speaking, more characters mean more helpful details and more opportunities to show up in Pinterest search results.
  • Good descriptions are an accurate representation of what is in the image. Avoid URLs, which look messy, and first-person messages that don't make sense out of context.
  • Pins get distribution on Pinterest for a very long time: so avoid details like sales, prices or promotions, that might not be accurate later.
Specify canonical sources
Many Pins on Pinterest are created from images shown in search results, catalog pages, index pages or other non-canonical locations. In many of these cases, the URL for the image may not be the URL you want, potentially causing lost engagement and traffic to your site.
Use the
data-pin-url
attribute to associate an image to a particular URL. This will guarantee that the Pin is linked to the source URL that you want. This is particularly useful for pages with multiple images that link to various places on your website.

Follow Button

The follow button lets Pinners see your added Pins and easily follow your business's Pinterest page.
Before you start, make sure you've included the
pinit.js
script on your page. Remember, only include this once per page, no matter how many Pinterest widgets you use, including it more than once may cause unpredictable results.
See Add ons overview for tips about how to best include our JavaScript on your site.
<script type="text/javascript" async defer src="//assets.pinterest.com/js/pinit.js"></script>
To add a follow button to your page, add the following code to your site where you want the follow button to appear. Change the link to point to your Pinterest page and edit the text to display your profile's name.
<a href="https://www.pinterest.com/<your-profile-here>/" data-pin-do="buttonFollow">
  Your&nbsp;profile&nbsp;name&nbsp;here
</a>
Was this page helpful?