Plugin to write WordPress themes w Object-Oriented Code and the Twig Template Engine

Installs: 1 361 040

Dependents: 84

Suggesters: 5

Security: 0

Stars: 5 154

Watchers: 131

Forks: 499

Open Issues: 242

2.0.0-beta.1 2022-08-04 19:34 UTC

This package is auto-updated.

Last update: 2022-11-24 07:13:18 UTC



By Jared Novack (@jarednova), Lukas Gächter (@lgaechter), Coby Tamayo (@cobytamayo), Maciej Palmowski (@palmiak_fp), Nicolas Lemoine (@nlemoine) Upstatement and hundreds of other GitHub contributors

Build Status Coverage Status Scrutinizer Code Quality Latest Stable Version WordPress Rating

Because WordPress is awesome, but the_loop isn't

Timber helps you create fully-customized WordPress themes faster with more sustainable code. With Timber, you write your HTML using the Twig Template Engine separate from your PHP files.

This cleans up your theme code so, for example, your PHP file can focus on being the data/logic, while your Twig file can focus 100% on the HTML and display.

This is what Timber's .twig files look like (from this Hello World example)

{% extends "base.twig" %}
{% block content %}
  <h1 class="big-title">{{ foo }}</h1>
  <h2 class="post-title">{{ post.title }}</h2>
  <img src="{{ post.thumbnail.src }}" />
  <div class="body">
	{{ post.content }}
{% endblock %}

Once Timber is installed and activated in your plugins directory, it gives any WordPress theme the ability to take advantage of the power of Twig and other Timber features.

Looking for docs?


The GitHub version of Timber requires Composer and is setup for inclusion within a theme or plugin. If you'd prefer one-click installation for your site, you should use the WordPress.org version.

cd ~/wp-content/themes/my-theme
composer require timber/timber

If your theme/plugin is not setup to pull in Composer's autoload file, you will need to

/* functions.php */
require_once(__DIR__ . '/vendor/autoload.php');

After this line, initialize Timber with

$timber = new \Timber\Timber();

What Now?

Setup the Timber Starter Theme. Once you have that installed in your WordPress setup, continue reading the Getting Started guide to Themeing.

Mission Statement

Timber is a tool for developers who want to translate their HTML into high-quality WordPress themes through an intuitive, consistent and fully-accessible interface.

  • Intuitive: The API is written to be user-centric around a programmer's expectations.
  • Consistent: WordPress objects can be accessed through common polymorphic properties like slug, ID and name.
  • Accessible: No black boxes. Every effort is made so the developer has access to 100% of their HTML.

What does it look like?

Nothing. Timber is meant for you to build a theme on. Like _s it comes style-free, because you're the style expert. Instead, Timber handles the logic you need to make a kick-ass looking site.

Who is it good for?

Timber is great for any WordPress developer who cares about writing good, maintainable code. It helps teams of designers and developers working together. At Upstatement we made Timber because while our entire team needs to participate in building WordPress sites, not everyone knows the ins-and-outs of the_loop(), codex and PHP (nor should they). With Timber your best WordPress engineer can focus on building the .php files with requests from WordPress and pass the data into .twig files. Once there, designers can easily mark-up data and build out a site's look-and-feel.

Related & Official Projects

  • Twig The template language used by Timber.
  • Timber Starter Theme The "_s" of Timber to give you an easy start to the most basic theme you can build upon and customize.
  • Timber Debug Bar Adds a debug bar panel that will show you which template is in-use and the data sent to your twig file.

Related Timber Projects

Projects that use Timber

  • Branch Bootstrap 3 + Timber = Branch starter theme!
  • Flynt a component based WordPress starter theme built on Timber and ACF Pro
  • Gantry5 a framework for theme development
  • Hozokit a component based starter theme
  • Seedling a starter theme using Bootstrap 4

Helpful Links


Please post on StackOverflow under the "Timber" tag. Please use GitHub issues only for specific bugs, feature requests and other types of issues.

Should I use it?

It's MIT-licensed, so please use in personal or commercial work. Just don't re-sell it. Timber is used on tens of thousands of sites (and tons more we don't know about)

Contributing & Community

We love PRs! Read the Contributor Guidelines for more info. Say hello, share your tips/work, and spread the love on Twitter at @TimberWP.


The Official Documentation for Timber is generated from the contents of this repository: