🏛️ 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
- Escaping Issues: Not escaping output properly
- Licensing Problems: Non-GPL compatible code or resources
- Plugin Territory: Including functionality that belongs in plugins
- Sanitization: Not sanitizing user input
- Prefixing: Using generic function/class names
- Hidden Links: Credit links that can't be removed
- External Dependencies: Loading from CDNs
- Selling/Upselling: Too aggressive promotion
- Code Quality: PHP errors, deprecated functions
- 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