Learn how to make custom HTML Tumblr themes

Start chapter 1 Skip to the blog

Complete book

Build Themes is a free and complete book for HTML, CSS and jQuery Tumblr theme development.

Create a real theme

Learn by creating a Tumblr theme from scratch with accompanying explanations and demos.

Become a theme pro

Explore the code professional theme developers use to add advanced features to their themes.

On our blog

Delve deeper into the world of Tumblr themes. The Build Themes blog has the latest coverage on the Tumblr theme system plus free tutorials and resources.

Github now available in Tumblr Theme Garden


The mysterious Github button which appeared in the Theme Garden’s new theme page (then disappeared) has come to fruition, with what appears to be full functionality today.

Clicking the Github button allows you to authenticate your Github account with Tumblr. Here’s a screenshot of the process:


Next, you’re able to fill in details of your project and import the theme’s source code into the Tumblr Theme Garden:


If you’re looking to dive into Git, Pro Git by Scott Chacon is a great book available for free on the Git website.

Edit: Feature is also documented by Tumblr

Github integration coming to Tumblr Theme Garden?


Tumblr’s new themes page for the Theme Garden sports a fancy new Github switch (zoomed in for maximum excitement):


Only problem is it doesn’t seem to do anything…at the moment (unless I’m missing something). Hopefully there’ll be an official announcement soon. 

This could mean version control goodness with Github. If you haven’t used Git before, it’s an easy and safe way to track changes and backup code, and work with other developers on the same code.

Stay tuned!

Edit (10.30 PM on 12 Nov): The Github button is no longer shown on the theme page.

Tumblr’s new theme customize panel

Tumblr today announced a brand-new customize panel.

Here’s some of the new stuff they released, with some additional commentary.



In line with Tumblr’s new found beautiful flat-design, the customize panel has received a major make-over.

Real-time code preview

Like in WordPress, Tumblr brings “real-time” preview.

The preview now, by default, shows you your actual Tumblr posts, instead of the sample posts (you may change this setting in “advanced options”).

Plus everything feels much faster. Those extra page reloads, as in the old version, are hidden away.

Browse themes with filters and search


Right now, Tumblr’s showing off their premium themes in the themes panel.

Installation is now seamless, just click on a premium theme, and it’ll show up in the preview, allowing you to try out customizations before you buy.

New color picker


Looks pretty similar … just newer buttons!

Fonts! Fonts! Fonts!


Tumblr adds a slew of web fonts, that previously weren’t included.

New pages


You can now easily create pages, without the old pop-up page.

To use the preview of the page, you seem to have to click on the “update preview” button (no automation so far).

Better code editor


Okay here’s the best to last (for theme developers at least)!

A brand-new code editor, that can be expanded (just drag on the gray area with the three dots).


Clicking on the options menu gives you access to a bunch of quick-access features such as the theme docs, and search + replace.

Tumblr’s Theme Garden in 2013


Below are our 2013 Tumblr Theme Garden stats, putting Tumblr’s changing themes mix, and (slightly) bigger Theme Garden in numbers.

At the height of Tumblr’s Theme Garden in mid 2011, at least 918 themes were visible. By October 2012, the number of themes dropped to 171.

Today, in October 2013, we’ve seen a slight rise to 220 themes. A total of 49 new premium and free Tumblr themes.


2013 has seen the continued rise of premium Tumblr themes (themes costing between $9 to $49).

65% of all themes are now premium. There is a selection of 77 free themes, compared to 143 premium themes.

One in four themes in the Tumblr Theme Garden are created by one company—Pixel Union.

Tumblr themes ‘drop-down lists’ now documented

Tumblr’s new customization feature that allows users to quickly change the design and functionality of a theme with simple options from a drop-down list, is now fully documented by Tumblr.

"With this new feature, you can now give users several options for a particular design element," said Tumblr in a theme developer announcement.

"Our new theme, Optica, shows the drop-downs in action”.

Here’s a suggested snippet of code for enabling options from the documentation, provided in the documentation (and used in Optica):

        <!-- DEFAULTS -->
        <meta name="select:Layout" content="regular" title="Regular">
        <meta name="select:Layout" content="narrow" title="Narrow">
        <meta name="select:Layout" content="grid" title="Grid">
        <div class="content {select:Layout}">

Also check out our previous post, that explores enabling the drop-down lists to style an avatar like in Optica.

Tumblr’s new “select” option, seen in Optica

Edit (16 July 2013): Tumblr’s new “drop down list” is now officially documented!

Tumblr’s latest theme release, Optica, along with a beautiful new design also shows off a new undocumented feature that lets users select theme options.

Here’s a screenshot of Optica’s customize panel:


Notice the ability to select theme options. When you select an option Tumblr generates the correct code like so:


Normal layout


Narrow layout


Grid layout

Very, very powerful and much easier than using a number of checkboxes like in the old customize panel.

Using “select” in your themes

As “select” doesn’t have any documentation yet, I’ve dug a bit into Optica’s code. For this example, I’ll concentrate on the avatar style, since it’s the simplest to understand.

In Optica, the developers let users select between avatar styles (square, circle, or hidden) and layouts (regular, narrow, grid). In the META elements (placed with the HTML head tag, like usual) here’s what they’ve done:

        <meta name="select:Avatar style" content="square" title="Square">
        <meta name="select:Avatar style" content="circle" title="Circle">
        <meta name="select:Avatar style" content="hidden" title="Hidden">

        <meta name="select:Layout" content="regular" title="Regular">
        <meta name="select:Layout" content="narrow" title="Narrow">
        <meta name="select:Layout" content="grid" title="Grid">

Very simply, the name attribute is similar to what we’ve seen elsewhere in Tumblr. Just specify the theme option (in this case “select”), and then attach it to the name of the option. The content attribute is what value will be outputted (more on this later), whilst the title is what is shown in the drop down box.

In the HTML you can then call the value in the form of {select:x}, where x refers to the META name. So, to get the value the user selected for the avatar, just code in:

<header class="masthead {select:Avatar style}">
    <img src="{PortraitURL-128}"/>

In the CSS, just target the class we’ve added like so:

.square img {
    border-radius: 0;

.circle img {
	border-radius: 50%;

.hidden img {
	display: none;

Simple, right?

jQuery grids: Masonry at version 3, plus Mason.js released

Today we’ll quickly look at two but very notable developments in the world of jQuery grid plugins this month.

Masonry hits version three


Masonry, the popular jQuery library for creating Tumblr grid themes and other cascading grid layouts, has received a major update improving support for “percentage widths, gutter, [and] stamps”.

Along with the update, documentation has been refreshed for the new options. Check out the appendix for information about upgrading from version two.

Mason.js: New grid plugin for jQuery


Mason.js is a new plugin created by Drew Dahlman.

Mason.js is for creating a “perfect” gapless grid. “This is not Masonry, or Isotope or Gridalicious. Mason fills in those ugly gaps, and creates a perfectly filled space,” says Dahlman.

Download at Github

Quick ‘n easy post type filters with Tumblr/JS plus pages

In this tutorial we’ll explore a simple and fast way to create pages with recent posts, based on their post type, using Tumblr’s blog embed code:

<script type="text/javascript" src="http://buildthemes.tumblr.com/js"></script>

The finished product, will be a page with your preferred post type, looking similar to this:


Creating the page

First we’ll create a page from the theme’s customize panel:


We’ll use a standard page, set where the page should live and its name then click on the HTML button:


Below is a list of code to embed different types of Tumblr posts: text [line 1], photos [2], quotes [3], links [4], chat [5], audio [6] and video [7]. Copy the line for the type of post filter you wish to display. For this example, we’ll use grab all text posts using line one.

<script type="text/javascript" src="http://buildthemes.tumblr.com/js?type=text"></script>
<script type="text/javascript" src="http://buildthemes.tumblr.com/js?type=photo"></script>
<script type="text/javascript" src="http://buildthemes.tumblr.com/js?type=quote"></script>
<script type="text/javascript" src="http://buildthemes.tumblr.com/js?type=link"></script>
<script type="text/javascript" src="http://buildthemes.tumblr.com/js?type=chat"></script>
<script type="text/javascript" src="http://buildthemes.tumblr.com/js?type=audio"></script>
<script type="text/javascript" src="http://buildthemes.tumblr.com/js?type=video"></script>

Then the HTML window, paste the code.

Be sure to change the Tumblr username from “buildthemes” to the URL of your blog.


Then click “update” and save the page.

Extra stylin’


By default, Tumblr will simply use the default theme’s style for the page. With CSS we’ll remove some of the default numbering of posts, and add a background to the posts.

In the customize panel’s advanced section, add the following extra Custom CSS:

.tumblr_posts {
    margin: 0;
    padding: 0;
	list-style: none;

.tumblr_post {
	padding: 4%;
	background: rgb(248, 248, 248);
	box-shadow: 1px 1px 0px 2px rgba(0, 0, 0, 0.07);
	margin-bottom: 2%;

.tumblr_title {
	font-size: 1.5em;
	text-transform: uppercase;


Be sure to save the theme, and you’re done!