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.
<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>
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:
og:imagetag with an image at least 500px wide, with an aspect ratio less than 3:1. It'll use the
og:descriptionfor the post caption.
og:titlewill be used for the title,
og:descriptionfor the caption, and the canonical URL will be used as the link post URL.
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
|Option||Description||Data attribute||Query string parameter|
|Post type||Tumblr post type. Valid options are: text, photo, link, quote, chat, or video||
|Tags||A comma-separated list of tags||
|Title||Used in Text, Link, and Chat post types||
|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.
|Caption||Used in Photo, Link, Video, and Quote posts.||
|Show attribution||Whether or not to include an attribution in the post body that read, "via "||
data-title: Title of the Text post
data-content: Body of the Text post
data-content: A single photo URL or a comma-separated list of photo URLs for a photoset.
data-caption: Photo post caption.
data-content: The quote.
data-caption: The quote source (speaker and citation).
data-title: Title of the Link post.
data-content: The link's target URL.
data-caption: A description of the link.
data-title: Title of the Chat post.
data-content: The chat body (what the speakers said).
data-content: Video URL or embed code.
data-caption: Video post caption.
You can configure the style of your share button with these data attributes on the button anchor tag:
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:
|2||Canonical link 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:
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.
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:
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.
You can localize your button with the
data-locale attribute on the button anchor tag. Tumblr supports the following languages: