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.

OptionDescriptionData attributeQuery string parameter
Post type Tumblr post type. Valid options are: text, photo, link, quote, chat, or video data-posttype posttype
Tags A comma-separated list of tags data-tags tags
Title Used in Text, Link, and Chat post types data-title title
Content The main content of the post will vary depending on the post type you're using. For a Photo post, it will be a photo URL. For a Quote post, it will be the quote.

See Post Content by Type below for details.
data-content content
Caption Used in Photo, Link, Video, and Quote posts. data-caption caption
Show attribution Whether or not to include an attribution in the post body that read, "via " data-show-via show-via

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:

OptionPossible ValuesDefault
data-color blue
black
white
blue
data-notes top
right
none
none

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:

PriorityData Source
1 data-href attribute on the button anchor tag
2 Canonical link element
3 og:url meta element
4 The URL of the page

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 540x600 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:

LanguageLocale Value
English en_US
German de_DE
French fr_FR
Italian it_IT
Japanese ja_JP
Turkish tr_TR
Spanish es_ES
Russian ru_RU
Polish pl_PL
Portuguese pt_PT
Portuguese pt_BR
Dutch nl_NL
Korean ko_KR
Chinese (Simplified) zh_CN
Chinese (Traditional) zh_TW