WordPress Options and Theme Modifications

When The Customizer (once called The Theme Customizer) became part of WordPress, we saw a resurgence in the Theme Modification API.

The Theme Customizer

At one point in WordPress history, the get_theme_mod and set_theme_mod was how we handled theme modifications (hence the function names). Then, we began to use the options table as a way to manage the various settings for our plugins.

And then we began to use the options table as an easy to way to store settings for our themes. It was like we moved the Theme Modification API to the backseat and pushed forward with options.

Should we have done that (or does it even matter)? And what’s the difference in these APIs, anyway? Why do we still have both of them, which is best to use and when?

Using WordPress Options (Or Theme Modifications)

When it comes to the WordPress Theme Modification API, I don’t know much of its history. That is to say I know it exists and its purpose is a way to store settings for themes, but not much beyond that.

The Codex says:

Introduced in WordPress 2.1.0, Theme Modification API consists of all functions and hooks that are part of the WordPress API related to the use of Theme modification values. These functions can be used by theme authors to save (and retrieve) modifications to their themes as WordPress options.

But I also know that developers have been using the Options API for years to save plugin and theme settings.

Moving From Modifications To Options

I don’t know when or why we moved to the Options API, but I know that we shouldn’t ignore the Theme Modification API. Anyone who has done extensive work with The Customizer would likely agree.

Sometimes, though, I’m asked if we should have moved from one API to the other. At one time, I would’ve said “just stick with one since that’s simpler,” but I don’t feel that way anymore.

Instead, just as themes are for presentation and plugins are for functionality, we should be using the proper APIs for our themes and our plugins.

And this implies a difference in the APIs, doesn’t it?

An API For Each Purpose

But what’s the difference? To try to keep this simple:

  • Theme Modifications represent what’s available for a specific theme. WordPress saves all options managed by The Customizer as a single array in the database.
  • Options are available to any theme and/or any plugin. In contrast to the The Customizer, WordPress saves each value as a single record in the database.

Pretty easy to keep straight, right? I’d go as far as making this case:

If you’re working on a theme, use Theme Modification API (and add support for The Customizer). If you’re building a plugin, use the Options API.

And that’s my general rule of thumb. There are always exceptions, but this is the gist of it.

Why We Have Two APIs

And this is why we continue to have both APIs: One supports themes, one supports plugins.

Unfortunately, we’ve gotten so far remove from the difference in themes and plugins and the intent of the APIs, and we have so much misinformation floating around, there’s no clear between the delineation between the two APIs.

I’m not making the case for going back and refactoring how all your themes work. I do think as professional WordPress developers, we should properly incorporate these two APIs.

Though our old code may not do this (I know some of mine doesn’t), our future code doesn’t have to be that way.

16 Replies to “WordPress Options and Theme Modifications”

  1. Well, I’ve got a half-baked theory. From set_theme_mod() description:

    Creates or updates a modification setting for the current theme. Along with get_theme_mod() this function sometimes offers theme developers a simpler alternative to the Settings API when there is a need to handle basic theme-specific settings

    Simpler alternative. Indeed. The Settings API is either tolerated or hated by developers. A lot of us simply use what we regard as the simpler way: the Options API. This means you get very familiar with handling options one way and don’t bother with anything else at all including the Theme Settings API.

    One API to rule them all.

  2. I recently wrote a plugin that helps save different setups for the same theme (colors, widget usage/placement, etc). It relies on theme_mods and works great IF theme developers use that for there Theme settings. An example of how it is disconnected is where Genesis uses WordPress header and background support (both go to theme_mods) but use Options API for their layout and color scheme settings. Kind of a fail IMO. Theme Options API is great because devs can tap into all themes with expected results rather than supporting nth number of named options. My experience is +1 for using Theme Modification API.

    1. Yeah – I’m personally a fan of the Theme Mod API for, well, theme modifications. But if I’m doing plugin work or something where I need to temporarily store flag values or something like that, then the Options API fits well :).

      1. I just read how my comment didn’t’ make sense and you corrected me because you knew what I thinking. Thanks for reeling the conversation back in.

        Btw great post, I am going to be referencing this for months.

  3. One other important point to make about theme mods is that the “per theme” part applies to child themes as well. So, mods saved for a parent theme are different than the mods saved for a child theme and vice versa.

    This can make for an extremely powerful or frustrating experience for your users. It depends on your theme, its options, and its audience.

    Some options tend to be better as theme mods, such as fonts and colors. However, some options are better to be persistently handled across parent and child themes. That’s why I advocate a mixed approach of the Theme Mods API and Options API in some cases.

    Generally speaking though, use Theme Mods for themes. Not to mention, there’s some extra hooks available that makes it even nicer.

    1. My opinion is that a theme, it’s child, even it’s greatgrandbaby should all have their own option of display (inherited from ancestry). Theme Mod API actually will inherit parent modifications by default. A child would need to reset this behavior, making it perfect for the design. I think the frustration is likely caused by themes using Options API instead, and the idea that children have to compete rather than compliment.

      1. The problem is theme mod does not inherit anything from parent theme in reality and that makes it not so great choice for themes providing customization like layout and other stuff that should have effect of child themes too.

        Justin is on the point about the usage but mixing options and mods is confusing/making it difficult to remember for the 3rd party developers modifying where to use it.

        Depending on the scope of the theme, if it has more global styles/settings which affects parent/child all, It is better to use options instead of theme mod.

        Theme mod is a great choice if parent/child do not share many of the preferences.

          1. I am of the opinion that we should use theme mods for all things theme, and if children do not override the parent with it’s own mod, it should use the parent’s.

            This make sense to me – it follows the inheritance model well.

            1. The parent has its theme modifications
            2. The children has its theme modifications and falls back to the parent’s if nothing is declared.
    2. Some options tend to be better as theme mods, such as fonts and colors. However, some options are better to be persistently handled across parent and child themes. That’s why I advocate a mixed approach of the Theme Mods API and Options API in some cases.

      Definitely. I’d never imply to work in terms of absolutes but I think it’s important to strive for one over the other depending on your work.

      Though I don’t think you’re really saying anything in opposition to that. I’m just throwing it out there :).

      Generally speaking though, use Theme Mods for themes. Not to mention, there’s some extra hooks available that makes it even nicer.


  4. The problem is the distinction between Theme and Plugin. A theme is able to do all things, because of it’s ultimate access. However, because of this, themes TRY to do all things when they shouldn’t. Theme Mods should be LAYOUT AND PRESENTATION related only.

    WordPress has not been very successful at making this a clear end goal. The market is flooded with themes that should be split into plugins, and some should be plugins altogether (@see layers()).

    I like Justin’s reaction here, but I feel it is timid. Distinct lines should be drawn when using these two very different API’s for good reason, but there are none. I call the comment timid because NO ONE IS CALLING OUT WORDPRESS FOR IT’S FAILURE.

    Themes have no business creating CPT, or Widgets, or injecting custom robot meta to the head. That is the place for plugins. Themes should NEVER save data to the options table without going through Theme Mods to begin with really.

  5. One other note, a correction to “Options are available to any theme and/or any plugin. In contrast to the The Customizer, WordPress saves each value as a single record in the database.” The Customizer API has the ability to save as 'type' => 'option' or 'type' => 'theme_mod'.

      1. This is true – thanks for pointing that out. It’s good to have this distinction in the comment thread so others can read it and pick up on it.

        I should’ve updated to post to say that unless otherwise specified.

  6. The customization API doesn’t seem to be working for me, but I believe in time it will be able to compete with some of the more mature options frameworks out there. I could easily enable a ‘Customizer Page’ in the premium restaurant theme I purchased at http://www.templatemonster.com/wordpress-themes.php, and it is being developed continuously which is great. However, there are still plenty of other methods that theme authors already use to implement theme options.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.