Things to Know About Custom Tumblr Theme Design

Things to Know About Custom Tumblr Theme Design

Tumblr has done a lot of growing over the past few years. Recently I’ve had to develop a few themes inside of Tumblr for part of a larger overall campaign. Coming from WordPress, I appreciated the platform’s simplicity, but wasn’t sure about how customizable it would actually be. I was under the impression that custom theme design was a lot more complicated than it actually is.

This post goes over a few of the basic questions that I’ve come across in starting with custom theme development for Tumblr blogs. It’s not a definitive list, but should help get you moving the first time through.

Tumblr is not a typical content management system. It’s a simple way to put categorized types of information online in blog format. You will probably not be able to teach your theme new tricks by expanding the API. The focus is on rearranging the blog’s content using basic HTML and CSS, just like the CSS Zen Garden project started years back.

You can still customize, just within the limits of basic check boxes, text inputs, and color swatches. If you think about it, that’s really all you need.

Where Do My Images Go?

Tumblr's Static Uploader

Unless you’re a typography purist, you’ll probably use a few images in theme design. In the past, posting images to “closed” systems had involved an upload to a third-party (e.g. Image Shack) and then linking images that way. As it turns out, you don’t have to host your own theme files. Tumblr offers a static file uploader for use with custom themes. Just make sure to respect the uploader, and keep it limited to theme assets only. If you turn it into a personal dumping ground, your account can get banned.

Build in Blocks

Content types break down into blocks. You can specify a photo post using Block:Photo and a quote using Block:Quote. Your theme’s HTML is really just a single page with all possible options on it. When a visitor loads the page, the content displays according to the structure defined by its block. All post types are encapsulated by the {block:Posts} tag.

A Sample Block

You Start with Some Basic Variables

The theme HTML declares Tumblr variables using a special markup that looks something like this:

In most cases, these variables represent options available within the customize menu in Tumblr’s dashboard. In the snippet above, the “MetaDescription” will load whatever the Info>Description box contains. MetaDescription is an example of one of the basic variables that every theme starts with. Think of it like a simplified version of WordPress’ template tags.

Custom Options are Easy

A Sample Options Panel

Most Tumblr users will probably not know HTML and CSS like you do. If you plan on developing a theme to release to the general community, it’s a good idea to make as much of the theme controllable from the customize menu as possible. The default code editor is not the most elegantly designed, and it’s definitely not something users should have to change font colors from.

If you have to use an API that isn’t already supported within Tumblr’s initial tags, you can do so with some JavaScript and a custom field. As mentioned above, server-side scripting is off the table.

Defined via Meta Tag

You declare all custom options using a meta tag in the top of the theme’s HTML. If we wanted to specify a field for favorite book, the code might look something like this:

This would cause the following option to display inside the theme customization screen:

Favorite Book Option

You display the option’s value within the theme using a custom Tumblr tag:

Notice how the prefix “text:” designates the type of field to display, and the content attribute specifies the default value. Spaces in the option’s name do not matter. The full documentation has a complete list of available options including color swatches, image uploads, and checkbox IF statements.

Comments Work Differently

A Tumblr Comment Feed

One of the most frustrating things to WordPress developers about Tumblr is the lack of comments. Users can certainly respond to posts, but not in the traditional “Type Message Here” way. Tumblr comments come in a few flavors of responses, and they take some getting used to for theme development.

If I like another Tumblr blog’s post, I can reblog (post it to my page) with more comments in the post body. I could also “Like” a post without reposting it myself. In either case, Tumblr places a trackback line into original post that summarizes your action.

If you look at a few active posts on Tumblr, you see how posts can get away without have direct comments through this type of sharing. The staff blog announced a new “Notes” feature to add another option for post feedback, but not many themes support it yet.

Other Expansions

In the past 6 months, the Tumblr team has continued to expand the platform’s capabilities. They’ve added the ability to ask questions, get user feedback, and integrate Twitter accounts into themes. Before reinventing the wheel with JavaScript inserts, make sure that it doesn’t already appear within the growing documentation.

A Growing Trend

Tumblr Theme Garden

These are just a few starting points for people starting out with Tumblr customization. The official theme documentation has a more technical overview of possible theme routes, and it’s a great place to start with any questions. There’s still a learning curve (especially for the type of customization seen in the premium theme section) but like most things on the internet it just takes some time to get used to. The folks at MetaLab have done quite a few compelling designs for Tumblr, including a few of the new premium options available in the Theme Garden.

Based on Google searches, custom theme development is a topic that is only starting to get the coverage and tutorials it needs.  Nettuts recently published a full walk-through guide for its premium subscribers, but it was difficult to find many other widely available tutorials. Is this something you would like to see Build Internet focus on in upcoming posts? Let us know in the comments.

Posted Monday, April 26th, 2010 · Back to Top


Add Comment

54 Comments 31 Mentions

  1. Smashing Share Author Editor

    Nice post. We also posted something about tumblr today on our blog :)


  2. Trevor Author Editor

    Nice post. Perfect timing – I’m just working on my first tumblr theme and needed to orient myself. Thanks for posting!


  3. Thiago Cavalcanti Author Editor

    The way you put it makes it seem really easy. I’m sure there must be some gotchas not covered here…


  4. Ted Thompson Author Editor

    Great post, very helpful. Thanks Ted


  5. Nicole Author Editor

    Thanks for the info, have been planning on trying to design and devlop my own Tumblr theme for some time now.


  6. jiewmeng Author Editor

    very informative article, i would look forward to a more in depth walk-through of development of a PSD to HTML5/CSS3 tutorial! maybe even improved with some jQuery?


  7. Andrew Author Editor

    I’ve recently starting working with Tumblr (started with WordPress) and I’d love to see more overview-style articles such as this.


  8. Digital Art Empire Author Editor

    great post be good ro see some more on Drupal to


  9. Rachel Author Editor

    Nice Post..Very useful..thanks


  10. Edmundo Junior Author Editor

    Great post! Sure I would love some more about Tumblr development :D

    Like you say, it’s very hard to find some good stuff about custom themes for Tumblr.


  11. neel Author Editor

    Great tutorial thanks for sharing. i will definitely try this tutorial on my profile..


  12. marcelo Author Editor

    I have a tumblr-blog my own, I never gave much importance to it, maybe give you a deeper look. thanks!


  13. dffoto Author Editor

    Nice post. Thanks))


  14. Vernessa Author Editor

    Your tutorial clears up a few things for me. Couldn’t wrap my head around notes vs. comments. I haven’t created a theme for Tumblr yet, but I’m considering it. Thanks for the write-up and breakdown.

    One Question: Does the allowed HTML code support including blocks of source code within a post? For example, does it support [code ] or [ pre ] tags?


  15. dle 0ha web blog Author Editor

    Thanks man good tourtials.


  16. Mel Author Editor

    Extremely helpful, in fact it was just what I was looking for. I defiantly feel more prepared in making my own tumblr theme xD


  17. Gonzo the Great Author Editor

    Great tutorial, wanted this when I was designeing my custom Tumblr-theme!


    Thanks for sharing, Cheers & Ciao …


  18. Gonzo the Great Author Editor

    … eeehr, sorry! The link should be:


  19. NYC Injury Lawyer Author Editor

    Thanks for the excellent tutorial.


  20. SmashinGeeks Author Editor

    Very Nice Tutorial


  21. althoraya Author Editor

    wow god


  22. E Author Editor

    Thanks, this was great. I would love to see the topic of Tumblr customization explored more.


  23. Fuad NAHDI Author Editor

    great tutorial. it’s very useful for me. thanks


  24. xRommelx Author Editor

    thank you for this!!!


  25. Sandy Author Editor

    how come when i want to add music in my tumblr it doesn’t work. told me to click on the html source.
    but when the source comes up, it’s just blank.
    i want music in my tumblr, please help. :)


  26. Edelee Author Editor

    Hello! I’m trying to figure out how to publish my information to be posted on my tumblr page? Up to now, i still don;t know how. Can someone help?


  27. charlescuellar Author Editor

    voy a checarlo gracias


  28. Komedi Filmleri Author Editor


    Very good site ! thank you nice article. Thanks for sharing.


  29. ectopmall Author Editor

    Back in March, we introduced wholesale nfl jerseysyou to the Nike 78 project.


  30. Dalibor Vasiljevic Author Editor

    You can also check out Sezeen by Funkytional –


  31. Destroyer Author Editor

    Dnt do silly thngs here


    • Jetsyn Author Editor

      Tocduohwn! That’s a really cool way of putting it!


  32. Girish Author Editor

    Thanks for sharing. Tumblr is great.


  33. Ethan Author Editor

    Yes, I would like to see more posts like this! I am thinking about making a twitter based theme and I am new to tumblr theme design.


  34. HanHae Author Editor

    Awww.. I still need to work for my HTML theme just to have it?? OMO.. Okay.. I’ll just ask.. Where can we make this?? Anywhere? Or We could do this in NOTEPAD or sumthing?? BTW,, thanks..


  35. Michael Toney Author Editor

    Please do expand on customization tutorials for tumblr.
    I would really like to expand on the possibilities of this web platform.


  36. Simon Facciol Author Editor

    I have gone throught the whole process of designing a custom tumblr theme and it was pretty straight forward after you get to know the appropriate tags.

    Visit my tumblr blog and follow me so I will follow you back :)


  37. naguyin Author Editor


    I wanted to make one several months ago after I was introduced to it by a friend but was too overwhelmed by everything they threw at me.

    But this article is awesome. I’m getting a better feel for this. I think it’s time for round 2! :D


  38. Frontside Author Editor

    So my url links I put in my customize page keep getting scrambled. For example, my twitter name will go to ning and my email will go to the flickr box. It is really annoying. Now my header doesn’t show up anymore. Please let me know if you can help me out, its really aggravating. Thanks.


  39. P Author Editor

    YES! I’ve had Tumblr for a week, and already feel like I’m walking through a desert when it comes to formatting…


  40. Vitek Author Editor

    It’s for me.
    Thanks and regards,


  41. Shannon Author Editor

    Hey…I know you. You went to Minnechaug Regional High School.


  42. gamesliga Author Editor

    I put in my customize page keep getting scrambled. For example, my twitter name will go to ning a


  43. Tushar Acharya Author Editor

    I m using disqus so that readers can post their feedback… but then they have to search for the comment box … is there any way by which disqus box expands itself automatically ??? so that they can see where to comment ??
    please help ! i hv searched everywhere on internet but couldn’t find it :(


  44. Arjun Gehlot Author Editor

    Very good post. Thanks.

    It took me forever to learn about tumblrs static file uploader!


  45. Nate Williams Author Editor

    Great Post .. I would love to see sorting addressed .. can’t seem to find any documentation on how to sort posted based on notes, comments, popularity, etc


  46. wycieczki all inclusive Author Editor

    There’s noticeably a bundle to learn about this. I assume you made certain good points in features also.


  47. KLLkyasy Author Editor

    Вот прочла на форуме …. Профессиональная и срочная заправка картриджей в Ваш офис! Компания Картридж Мастер недорого заправит лазерные картриджи.

    [url=] заправка лазерных картриджей[/url], для лазерных принтеров и копиров.

    Срочный выезд на заправку картриджей в день обращения .
    [url=] тонеры для лазерных принтеров HP.[/url]
    Срочная [url=] заправка картриджа Samsung SCX 4623 / Samsung SCX 4828 / WC Xerox 3100 / Xerox WC 220 / HP C7115A / HP Q6511A / HP CB 435A / HP CC364А / Samsung – SCX 4100. [/url]
    [url=]Заправка картриджа с выездом аппарата Samsung SCX 4623 fn / Xerox WC 3250 / Samsung SCX 4623fn / Xerox WC 3500 / HP C4096A / HP Q2610A / HP C8061X / Samsung SCX 4200. [/url]


  48. Inspirational Quotes Author Editor

    Things to Know About Custom Tumblr Theme Design | Build Internet I was recommended this blog by my cousin. I’m not sure whether this post is written by him as no one else know such detailed about my difficulty. You are amazing! Thanks! your article about Things to Know About Custom Tumblr Theme Design | Build Internet Best Regards Veronica Cassetta


  49. Araceli Safrit Author Editor

    I have never ever imagined that studying can be so significantly exciting.


  50. Yen Petaccio Author Editor

    I have never ever imagined that studying can be so significantly exciting.


  51. Bryan Author Editor

    Thanks for the post! Will recommend for starting out on tumblr development. I would love to see some tutorials on tumblr theme development!


  52. Vicky Author Editor

    Another thing that is good about Tumblr is it offers many free beautiful themes. Design is important in creating an attractive website and these themes can guarantee you to have appealing website that you will surely love.


  53. Author Editor

    バッグが、自分のキャラクターであるのほとんど、ストーリーと多分伝説とレコード。しばらくの間、として詳細私は懸念している、名前市場に出回るから、愛らしい愛の物語。彼らが美しいアクセント鎖のようなジュエリーなど本物の革の詳細。Obsolutely から異なる各ハンドバッグ私は流通ここで。



Build Internet by One Mighty Roar. Since 2008.