Share Button Documentation

Overview

This documentation is for developers who want to control how their website content is displayed in Tumblr posts created by a share button widget installed on their page.

To get share buttons for your site, make one with our share button generator.

Basic button

On pages that include our share button JavaScript (below), the share button is simply an anchor tag with the class tumblr-share-button:

<a class="tumblr-share-button" href="https://www.tumblr.com/share"></a><script id="tumblr-js" async src="https://assets.tumblr.com/share-button.js"></script>

Note: If you have multiple share buttons on your page, you only need to include the JavaScript once, ideally right before the closing </body> tag.

Post content defaults

By default, the share button will create either a Photo Post or a Link Post depending on what Open Graph meta tags it finds on your page, but it can be configured to use whatever post type you want (see instructions below). These are the default options:

• Photo Post. The share button will create a Photo Post if it finds an og:image tag with an image at least 500px wide, with an aspect ratio less than 3:1. It’ll use the og:description for the post caption.
• Link Post. The share button will create a Link Post if it doesn’t find a suitable image for a Photo Post. og:title will be used for the title, og:description for the caption, and the canonical URL will be used as the link post URL.

Post content configuration

If you want the share button to create a particular type of post, you can do that with the following options. The options can be set as data attributes on the button anchor tag or as query string parameters in the URL in the button’s href attribute.

Post content by type

Text
data-title: Title of the Text post
data-content: Body of the Text post

Photo
data-content: A single photo URL or a comma-separated list of photo URLs for a photoset.
data-caption: Photo post caption.

Quote
data-content: The quote.
data-caption: The quote source (speaker and citation).

Link
data-title: Title of the Link post.
data-content: The link’s target URL.
data-caption: A description of the link.

Chat
data-title: Title of the Chat post.
data-content: The chat body (what the speakers said).

Video
data-content: Video URL or embed code.
data-caption: Video post caption.

Button style configuration

You can configure the style of your share button with these data attributes on the button anchor tag:

Canonical URL

For note counts to display and increment properly, you must provide the canonical URL of the page. The share button will look for it in these places and in this order:

If you are building a custom button (see below), you must pass the canonical URL in the query string, in addition to any post content. For instance:

http://tumblr.com/widgets/share/tool?canonicalUrl=http://cats.com

Build your own button

If you want to completely customize the design of the button to match your site, you can totally build your own. Have your custom button open a pop up window with this URL https://www.tumblr.com/widgets/share/tool and pass all the post content information as query string parameters, as described above. The share tool will resize itself to fit the post content, but we recommend that you open the window at 540×600 pixels.

Note counts

You can even display the note count on your custom button. You can pass the URL of your page to our share stats API endpoint and retrieve the note count, like so:

http://api.tumblr.com/v2/share/stats?url=https://www.tumblr.com/buttons

Be sure to cache the response on your end and only refetch it after 10 minutes or so. Tumblr caches the note count for URL shares for 10 minutes.

Button language

You can localize your button with the data-locale attribute on the button anchor tag. Tumblr supports the following languages: