Skip to main content

Course Progress

Loading...

🏛️ WordPress.org Theme Requirements

Understanding the official theme directory guidelines

Master the requirements for WordPress.org theme submission and approval

Learning Objectives

  • Understand WordPress.org theme guidelines
  • Learn required vs recommended practices
  • Master the submission process
  • Avoid common rejection reasons
  • Implement accessibility requirements
  • Follow coding standards
  • Understand licensing requirements
  • Navigate the review process

Why Submit to WordPress.org?

The WordPress.org theme directory is the official repository for free WordPress themes, offering massive exposure and credibility.

Benefits of WordPress.org Listing

  • Visibility: Millions of WordPress users browse the directory
  • Credibility: Official approval adds trust
  • Distribution: Easy installation for users
  • Updates: Automatic update notifications
  • Community: Access to WordPress community
  • Free Hosting: No hosting costs for your theme

Theme Review Process

1

Preparation

Test with Theme Check plugin

2

Submission

Upload theme ZIP file

3

Queue

Wait for review (2-6 weeks)

4

Review

Reviewer tests theme

5

Feedback

Required/recommended changes

6

Approval

Theme goes live

🔴 Core Requirements (MUST HAVE)

  • 100% GPL or compatible license REQUIRED
  • No obfuscated or encrypted code REQUIRED
  • Use WordPress functionality (no reinventing) REQUIRED
  • Properly escape all data output REQUIRED
  • Sanitize all user input REQUIRED
  • Validate and sanitize all untrusted data REQUIRED
  • Include copyright and license info in style.css REQUIRED
  • Use wp_enqueue_* for scripts and styles REQUIRED
  • No removal of admin notices REQUIRED
  • Screenshot must be representative REQUIRED
  • No phone home or tracking without consent REQUIRED
  • Theme Check plugin must pass REQUIRED

💻 Code Quality Requirements

  • No PHP or JS errors REQUIRED
  • Prefix everything (functions, classes, globals) REQUIRED
  • No deprecated functions REQUIRED
  • Secure code (no SQL injection, XSS, etc.) REQUIRED
  • Follow WordPress PHP Coding Standards RECOMMENDED
  • Use WordPress APIs and functions RECOMMENDED
  • Proper documentation and comments RECOMMENDED

Proper Prefixing Example

<?php
// WRONG - No prefix
function setup_theme() {
    // Theme setup
}

// CORRECT - With unique prefix
function mytheme_setup() {
    // Theme setup
}

// WRONG - Generic class name
class Walker_Menu extends Walker_Nav_Menu {
    // Custom walker
}

// CORRECT - Prefixed class name
class MyTheme_Walker_Menu extends Walker_Nav_Menu {
    // Custom walker
}

// WRONG - Global without prefix
$options = get_option('theme_options');

// CORRECT - Prefixed global
$mytheme_options = get_option('mytheme_options');

⚙️ Functionality Requirements

  • Display dynamic content correctly REQUIRED
  • Comments must work if enabled REQUIRED
  • Use WordPress features (menus, widgets, etc.) REQUIRED
  • Include default WordPress CSS classes REQUIRED
  • Support post formats OPTIONAL
  • Custom headers and backgrounds OPTIONAL
  • Editor styles RECOMMENDED

Required WordPress Features

<?php
function mytheme_setup() {
    // Required: Let WordPress manage the title
    add_theme_support( 'title-tag' );
    
    // Required: Add default posts and comments RSS feed links
    add_theme_support( 'automatic-feed-links' );
    
    // Required: Enable support for Post Thumbnails
    add_theme_support( 'post-thumbnails' );
    
    // Required: Register navigation menus
    register_nav_menus( array(
        'primary' => __( 'Primary Menu', 'mytheme' ),
        'footer'  => __( 'Footer Menu', 'mytheme' ),
    ) );
    
    // Required: Add support for core custom logo
    add_theme_support( 'custom-logo', array(
        'height'      => 100,
        'width'       => 400,
        'flex-height' => true,
        'flex-width'  => true,
    ) );
    
    // Required: Switch default core markup to output valid HTML5
    add_theme_support( 'html5', array(
        'search-form',
        'comment-form',
        'comment-list',
        'gallery',
        'caption',
        'style',
        'script',
    ) );
    
    // Recommended: Add support for responsive embeds
    add_theme_support( 'responsive-embeds' );
    
    // Recommended: Add support for Block Styles
    add_theme_support( 'wp-block-styles' );
    
    // Recommended: Add support for full and wide align images
    add_theme_support( 'align-wide' );
}
add_action( 'after_setup_theme', 'mytheme_setup' );

♿ Accessibility Requirements

  • Keyboard navigation must work REQUIRED
  • Skip links for screen readers REQUIRED
  • ARIA labels where appropriate REQUIRED
  • Proper heading hierarchy REQUIRED
  • Color contrast WCAG AA compliant RECOMMENDED
  • Focus indicators visible RECOMMENDED
  • Form labels properly associated RECOMMENDED

Accessibility Implementation

<!-- Skip Link -->
<a class="skip-link screen-reader-text" href="#content">
    <?php esc_html_e( 'Skip to content', 'mytheme' ); ?>
</a>

<!-- Proper Menu Toggle -->
<button class="menu-toggle" aria-controls="primary-menu" aria-expanded="false">
    <span class="screen-reader-text"><?php esc_html_e( 'Menu', 'mytheme' ); ?></span>
    <span class="menu-toggle-icon" aria-hidden="true"></span>
</button>

<!-- Proper Search Form -->
<form role="search" method="get" action="<?php echo esc_url( home_url( '/' ) ); ?>">
    <label>
        <span class="screen-reader-text">
            <?php echo esc_html_x( 'Search for:', 'label', 'mytheme' ); ?>
        </span>
        <input type="search" placeholder="<?php echo esc_attr_x( 'Search...', 'placeholder', 'mytheme' ); ?>"
               value="<?php echo get_search_query(); ?>" name="s" />
    </label>
    <button type="submit">
        <span class="screen-reader-text">
            <?php echo esc_html_x( 'Search', 'submit button', 'mytheme' ); ?>
        </span>
        <svg>...</svg>
    </button>
</form>

🚫 Prohibited Items

Themes with any of these will be immediately rejected
  • No "powered by" or credit links required BANNED
  • No selling of links or ads BANNED
  • No obfuscated/encrypted code BANNED
  • No external CDN dependencies BANNED
  • No tracking without user consent BANNED
  • No shortcodes in themes BANNED
  • No custom post types or taxonomies BANNED
  • No admin notices that can't be dismissed BANNED
  • No iframe loading from external sites BANNED
  • No base64 encoded content BANNED

📚 Documentation Requirements

  • License clearly stated REQUIRED
  • Copyright information REQUIRED
  • Credits for all resources REQUIRED
  • readme.txt file RECOMMENDED
  • Inline documentation RECOMMENDED
  • Setup instructions RECOMMENDED

readme.txt Format

=== Theme Name ===
Contributors: yourwordpressusername
Requires at least: 5.9
Tested up to: 6.4
Requires PHP: 7.4
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

== Description ==
Theme description goes here. Explain what your theme does and who it's for.

== Installation ==
1. Upload the theme folder to /wp-content/themes/ directory
2. Activate the theme through the 'Themes' menu in WordPress
3. See Theme Settings for customization options

== Frequently Asked Questions ==
= How do I set up the homepage? =
Navigate to Settings > Reading and set up a static front page.

= Does this theme support plugins? =
Yes, it's tested with WooCommerce, Contact Form 7, and more.

== Changelog ==
= 1.0.0 =
* Initial release

== Resources ==
* Normalize.css https://necolas.github.io/normalize.css/, (C) Nicolas Gallagher, MIT
* Font Awesome https://fontawesome.com, (C) Fonticons, Inc., CC BY 4.0
* Images: All images are from Pexels.com and are GPL compatible

🧪 Testing Requirements

  • Theme Check plugin must pass REQUIRED
  • Theme Unit Test data tested REQUIRED
  • Different content scenarios tested REQUIRED
  • WP_DEBUG enabled testing RECOMMENDED
  • Plugin compatibility testing RECOMMENDED
  • Multiple browser testing RECOMMENDED

Debug Configuration for Testing

// In wp-config.php for testing
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
define( 'SCRIPT_DEBUG', true );
define( 'SAVEQUERIES', true );

Common Rejection Reasons

These are the most common reasons themes get rejected. Avoid these issues!

⚠️ Top Rejection Reasons

  1. Escaping Issues: Not escaping output properly
  2. Licensing Problems: Non-GPL compatible code or resources
  3. Plugin Territory: Including functionality that belongs in plugins
  4. Sanitization: Not sanitizing user input
  5. Prefixing: Using generic function/class names
  6. Hidden Links: Credit links that can't be removed
  7. External Dependencies: Loading from CDNs
  8. Selling/Upselling: Too aggressive promotion
  9. Code Quality: PHP errors, deprecated functions
  10. Missing Features: No widget areas, no custom menus

Pre-Submission Checklist

  • Theme Check plugin shows no errors
  • All content properly escaped
  • All input properly sanitized
  • All functions/classes prefixed
  • License is GPL compatible
  • No external dependencies
  • Screenshot.png is 1200x900px
  • Theme tested with Theme Unit Test data
  • No PHP errors with WP_DEBUG on
  • Keyboard navigation works
  • Skip links implemented
  • readme.txt file included
  • All resources credited
  • No plugin functionality
  • No upselling or ads
  • Translation ready
  • Tested on latest WordPress
  • Responsive design works
  • Comments display correctly
  • Widgets and menus work

Best Practices for Approval

Tips for Quick Approval

  • Over-prepare: Fix more than just required items
  • Test thoroughly: Use multiple testing tools
  • Read guidelines: Review official documentation
  • Check other themes: Learn from approved themes
  • Be patient: Review process takes time
  • Respond quickly: Address feedback promptly
  • Ask questions: Use support forums if unsure
  • Keep it simple: Don't over-complicate
Join the WordPress Theme Review Team on Slack (#themereview) to get help and learn from experienced reviewers.

Practice Exercise

💻
Prepare for WordPress.org Submission

Get your theme ready for WordPress.org:

  1. Install Theme Check plugin
  2. Fix all required errors
  3. Fix recommended issues
  4. Test with Theme Unit Test data
  5. Enable WP_DEBUG and fix errors
  6. Check all escaping and sanitization
  7. Ensure proper prefixing
  8. Verify GPL licensing
  9. Create readme.txt file
  10. Test accessibility features

Additional Resources