The Most Common WordPress Theme Development Mistakes (and How to Fix Them)
Submitting a theme to the WordPress.org theme directory is a great way to share your work and contribute to the WordPress community. Currently, there are over 7000 themes in the directory, the most popular of which exceeds 300,000 active installations . (Not including Twenty____ Themes which are packaged with WordPress and have install counts in the millions.)
Before submitting your theme to the directory, it’s important to understand the review process first because if your theme doesn’t meet those requirements it can be rejected on the spot.
Themes that have 3 or more distinct issues may be closed as not-approved. However, theme authors may resubmit the theme once they’ve corrected the issues.
Reviewers are on your side and want to see your theme go live, once it meets the standards required. If your theme has only minor issues preventing it being included in the directory, your reviewer will work with you to fix those.
Unfortunately, if your theme has too many issues it will be closed as not-approved. If you decide to fix the issues you can upload the theme again – but it will join the back of the queue.
From my experience reviewing over 100 themes I’ve been able to identify the most common issues that prevent themes being approved. By sharing these with you in this article I’m hoping I can help you avoid getting stuck in the queue or rejected.
Uploading Your Theme
When you upload a theme, it joins the queue to be reviewed. On average it will take two months for your theme to reach the front of the queue and receive its first review. All reviewers are volunteers with limited time available to complete reviews. A variety of factors can affect the wait time. When more people volunteer to review themes, the queue moves quickly. Conversely, when themes with a lot of issues are submitted it slows down the queue.
By submitting a theme that meets all the requirements it makes the review process a lot smoother and ultimately your theme will be live sooner. In this guide, we are going to explore the most common issues that will keep your theme held up in the queue and prevent it from being approved.
Note: Theme authors that have a track record of submitting issue-free themes can apply to become ‘Trusted Authors ‘.
When you upload a theme, the first check that is performed is to see if the name is already taken. Frequently you will be told the name you’ve chosen is already taken, even if you can’t see a theme with that name in the directory.
How could that be? The reason is that the test isn’t checking against just the directory, it’s checking against the entire WordPress ecosystem. If a theme has been released anywhere (Github, ThemeForest, etc.) and has over 50 active installations, that name will be unavailable to use.
Note: if you’ve released your theme elsewhere and accumulated 50+ installations, you can still use that name in the directory.
Theme reviewers take security very seriously, there’s even a dedicated resource . An entire article could be written on writing secure themes, but in this section we are going to explore one aspect: escaping output.
Unescaped output places users of your theme at risk. Here’s an example of an unescaped value ($title):
$title = get_option( ‘my_custom_title’ );
‘ . $title . ‘
The problem with the above is that while we know what type of value $title should be, a string, we have not checked if that is the case.
alert(‘This is dangerous’);
The solution is to escape all output to ensure it only includes the type of data we are expecting.
Our example could be fixed like this:
$title = get_option( ‘my_custom_title’ );
‘ . esc_html( $title ) . ‘
The downside to using esc_html is that it strips all HTML tags. If $title included bold or italics, for example:
$title = ‘This article is very useful’;
echo esc_html( $title );
The word ‘very’ would not be bold on the frontend; instead it would output the code very.
This illustrates why it’s important to use the correct escaping functions for the context. If we were expecting some HTML in the output, we’d be better using wp_kses_post() or wp_kses() and setting the $allowed_html parameter.
Functions that output also need to be escaped: