Required

Topics

A theme must meet all of the following requirements to be included in the WordPress.orgWordPress.org The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://wordpress.org/ theme repository.

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.

Along with these checks, you should also run the theme through the Theme Check pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party. You can find a full list of what it checks here.

Note: If you are getting started with your first reviews, please read Become a reviewer. 

Warning: If you are a theme shop you should be selling under GPLGPL GPL is an acronym for GNU Public License. It is the standard license WordPress uses for Open Source licensing https://wordpress.org/about/license/. The GPL is a ‘copyleft’ license https://www.gnu.org/licenses/copyleft.en.html. This means that derivative work can only be distributed under the same license terms. This is in distinction to permissive free software licenses, of which the BSD license and the MIT License are widely used examples. to be in the WordPress.orgWordPress.org The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://wordpress.org/ repo (See explanation).

Example: If you have a Themeforest account and you’re selling themes on it, all those themes need to state on their sales page that they are 100% GPL compatible (Info).

Multiple Theme Author Accounts Multiple Theme Author Accounts

Warning: This is important,  so please read it carefully

You can have multiple accounts with the following restrictions:

  • You can’t have more than one (1) open ticket in any of the trac reports/queues or under review. That means you can’t have one (1) theme ticket from an account and another one from a secondary account, simultaneously open in any of the queues
  • Failing to respect the above requirement will result in the closing of all tickets and not having the possibility to upload those themes again. Also, a 1 month no upload possibility for each ticket closed. Depending on the severity of the case, you might also end up with a permanent ban on all your accounts
  • To avoid penalties, we request that you disclose all your accounts by emailing us at themes[at]wordpress.org

Top ↑

Accessibility Accessibility

Themes must include a mechanism that enables users to navigate directly to content or navigation on entering any given page. These links may be positioned off-screen initially but must be available to screen reader users and must be visible on focus for sighted keyboard navigators.

A minimally conforming skip link must:

  • Be the first focusable element perceived by a user via a screen reader or keyboard navigation
  • Be visible when keyboard focus moves to the link
  • Move focus to the main content area of the page when activated

Note that this only applies if there is something to skip past, such as a menu or larger header section or secondary widget area before the main content.

Top ↑

Keyboard navigation Keyboard navigation

Theme authors must provide visual keyboard focus highlighting in navigation menus and for form fields, submit buttons and text links.

All controls and links must be reachable using the keyboard.
All controls usable with the mouse must be usable with the keyboard, regardless of device and screen size. Including but not limited to responsive versions for small screens, mobile and other touch screen devices.

See https://make.wordpress.org/themes/handbook/review/accessibility/required/#keyboard-navigation

If the theme has the tag ‘accessibility-ready’ then it needs to meet these additional requirements.

Top ↑

Code Code

  • No PHP or JS notices
  • Validate and/or sanitize untrusted data before entering into the database. All untrusted data should be escaped before output. (See: Data Validation)
  • No removing or modifying non-presentational hooks.
  • Must meet all Theme Check requirements
  • Provide a unique prefix for everything the Theme defines in the public namespace, including options, functions, global variables, constants, post meta, wp_enqueue_script/style handle names, add_image_size names, wp_script_add_data keys, slugs/ids for new categories created with register_block_pattern_category etc. Theme nav menu locations and sidebar IDs are exceptions

Examples Examples

No PHP errors, warnings or notices

Themes must support PHP7. This means there must be no PHP errors, warnings or notices when running on PHP7. 

WordPress still supports lower PHP versions such as PHP 5.6 (read more). There should not be any PHP errors, warnings or notices if the theme is activated on a server with PHP 5.6.  Instead of downgrading the code to work for 5.6, the theme can include a PHP version check and deactivate the theme.

Have a valid DOCTYPE declaration and include language_attributes
<!doctype html>
<html <?php language_attributes(); ?>>
No adding shortcodes

The use of the add_shortcode() function is not allowed in themes as shown below:

add_shortcode( 'shortcode_name', 'shortcode_callback_func' );
No removing or modifying non-presentational hooks
remove_action( 'wp_head', 'wp_generator' );
remove_action( 'wp_head', 'feed_links_extra', 3); 
remove_action( 'wp_head', 'feed_links', 2); 

remove_action( 'admin_notices', 'update_nag', 3 );
remove_action( 'network_admin_notices', 'update_nag', 3 );

remove_filter( 'the_content','wpautop' );

add_filter( 'show_admin_bar', '__return_false' );

Top ↑

Core Functionality and Features Core Functionality and Features

  • Use WordPress functionality and features first, if available.
    If incorporated, features must support the WordPress functionality:  
  • Do not use features/APIs meant for WP Core use only e.g. admin pointers and private functions
  • No paywall restricting any WordPress feature
  • Avoid hard coding to modify content. Instead, use function parameters, filters and action hooks where appropriate. For example, wp_title should be modified using a filter
  • The theme tags in style.css and description must match what the theme actually does in respect to functionality and design. Don’t use more than 3 subject tags (See: Theme Tag List)
  • Use template tags and action/filter hooks properly
  • Include comments.php (via comments_template())
  • Themes may be backward compatible, but only for 3 major WordPress versions (version 5.0 if 5.3 is latest)
  • Themes should not remove, hide, or otherwise block the admin bar from appearing
  • Core theme activation UX should not be modified. There should be no redirect on activation behavior
  • All the notifications generated by a theme should use the admin_notices API and follow the core design pattern. They must be dismissible. Everything wrapped in the admin notice needs to follow core UI design for the notices
  • style.css must include in its header the Requires PHP and Tested up to fields.

Top ↑

Examples Examples

Use get_template_directory() rather than TEMPLATEPATH to return the template path
require_once( trailingslashit( get_template_directory() ) . 'inc/example.php' );
Use get_stylesheet_directory() rather than STYLESHEETPATH to return the template path
require_once( trailingslashit( get_stylesheet_directory() ) . 'inc/example.php' );

This example should come with an additional warning to check if the file exists first if not used in a child theme.

Include comments_template()
comments_template();

Should be called in at least all singular views.

Top ↑

Child themes Child themes

  • Themes must be able to have child themes made from them (Child theme ready).
  • Child themes must include more than minor changes (such as font and color changes) to the parent theme to be accepted. To make it easier on the reviewer, make sure you describe what modifications/features you did on top of the parent theme (in a ticket comment).

Top ↑

Main Stylesheet Main Stylesheet

The headers in style.css should follow the guidelines and requirements for the main stylesheet in the Theme Developer Handbook. The following headers are required:

Required headers
Theme Name: Name of the theme.
Author: The name of the individual or organization who developed the theme. Using the Theme Author’s wordpress.org username is recommended.
Description: A short description of the theme.
Version: The version, written in X.X or X.X.X format.
Requires at least: The oldest main WordPress version supported, written in X.X format. Themes are only required to support the three last versions.
Tested up to: The last main WordPress version the theme has been tested up to, i.e. 5.4. Write only the number.
Requires PHP: The oldest PHP version supported, in X.X format, only the number
License: The license of the theme.
License URI: The URL of the theme license.
Text Domain: The string used for textdomain for translation.

Top ↑

Readme.txt file Readme.txt file

A readme.txt file is required.

The sample readme presented below is a living document. It may change in the future.

  • The file header is required. There must not be any empty lines in the file header. Tested up to field should be present.
  • Right now, we share the readme validator tool with plugins. Warnings are required to be fixed, except for the Stable tag warning. Notes are not required to be fixed.
  • The other sections are optional, but we expect theme authors to include a list of license and copyright information somewhere in the theme: The resources section may be used for this purpose.

Top ↑

Example Example

readme.txt example
=== Theme Name ===
Contributors: (Should only contain WordPress.org usernames.)
Requires at least: 5.0
Tested up to: 5.2
Requires PHP: 5.6
License: GPLv2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html

Short description. No more than 150 chars.

== Description ==
Theme desc.

== Frequently Asked Questions ==

= A question that someone might have =

An answer to that question.

== Changelog ==

= 1.0 =
* Added new option

= 0.5 =
* Security bug addressed
* Changed thumbnail size

== Upgrade Notice ==

= 1.0 =
* Upgrade notices describe the reason a user should upgrade.  No more than 300 characters.

= 0.5 =

* This version fixes a security related bug.  Upgrade immediately.

== Resources ==
* magnify.jpg © 2014 Jane Doe, CC0
* supermenu.js © 2013-2015 James Today, MIT

Top ↑

Presentation vs Functionality Presentation vs Functionality

  • The theme options should not be pseudo custom post types and save non-trivial user data
  • Non-design related functionality is not allowed (See examples below).
  • Use starter content, existing content, or installation instructions instead of placeholder content. Installation instructions should only be visible to users with the edit_theme_options capability, not to visitors
  • Showing preview/demo data or manipulating the preview on WordPress.org is not allowed and can result in your user account being terminated
  • Adding custom blocks for Gutenberg (the new text editor in WordPress) is not allowed. Use a companion plugin instead
  • Placeholder/default images for posts without defined featured images need to follow these rules:
    • be generic (solid color, gradient or patterns)
    • they can’t display logos
    • they can’t display text, only accepted form would be displaying the image size, 400x300px
    • icons are allowed as long as they are not logos. A good example is a photo camera icon
    • they need to be bundled within the theme, don’t use third-party placeholder services directly (e.g: placeholder.com).

Top ↑

Examples Examples

Examples of plugin territory functionality

Analytics or tracking support
SEO options
Contact forms
Non-design related meta boxes
Resource caching
Dashboard widgets in the admin area
Custom Post Types and Shortcodes
Social media ‘like’, ‘follow’ and ‘share buttons’
Custom core editor (Gutenberg) blocks
Default logo
Session tampering

Top ↑

Importing or Downloading Importing or Downloading

  • Themes are not allowed to import content to a user’s site
  • Themes are not allowed to link directly to an XML, JSON, ZIP, or other files for direct download or import
  • Themes are not allowed to bundle demo content via an XML, JSON, ZIP, or other files

Top ↑

Examples Examples

Examples of importing content

If you are using the One Click Demo Import plugin, you can not use the setting where you link directly to the files. The following is not allowed, these are considered direct links:

'import_file_url'            => 'your-domain/demo.xml',
'import_widget_file_url'     => 'https://raw.githubusercontent.com/your-username/repo/master/widgets.wie',
'import_customizer_file_url' => 'your-domain/customizer.dat'

It does not make a difference to this requirement whether your files are placed on your domain, a demo site, or on Github.

Similar settings in other plugins are not allowed either. You are still allowed to recommend the plugins without the settings.

Top ↑

Documentation Documentation

  • Any custom features, templates, options or any limitations (for example menu restrictions), should be explained. Enough documentation should be provided.

Top ↑

Language Language

  • All theme text strings are to be translatable
  • Include a text-domain in style.css
  • Use a single unique theme slug – as the theme slug appears in style.css. If the theme uses a framework then no more than 2 unique slugs (like tgmpa, redux-framework, kirki or some other allowed framework)
  • Can use any language for text, but only use the same one for all text.
  • If a theme author chooses to include a POT file in their theme it needs to be kept up to date with all translation strings

Top ↑

Examples Examples

Text domain should be listed in the theme’s style.css head comment block

The text domain should be generated from the theme slug

Theme Name: Mim's Debacle
Text Domain: mims-debacle

Theme authors can include their own language packs that will supersede the WordPress ones

Theme authors have the choice of including their own language packs which will supersede the ones WordPress will self-install.
Here is an example how the text domain is loaded:

add_action( 'after_setup_theme', 'theme_review_setup' );
function theme_review_setup(){
    load_theme_textdomain( 'theme-slug', get_template_directory() . '/languages' );
}

For child themes loading the text domain would be:

add_action( 'after_setup_theme', 'theme_review_child_domain', 11 );
function theme_review_child_domain(){
    load_child_theme_textdomain( 'child-slug', get_stylesheet_directory() . '/languages' );
}

Top ↑

Licensing Licensing

  • Be 100% GPL and/or 100% GPL-compatible licensed
  • Declare copyright and license explicitly. Use the license and license URI header slugs to style.css
  • Declare licenses of any resources included such as fonts or images
  • All code and design should be your own or legally yours. Cloning of designs is not acceptable
  • Any copyright statements on the front end should display the user’s copyright, not the theme author’s copyright

Top ↑

Naming Naming

  • Theme names must not use: WordPress, Theme, Twenty*
  • Child themes should not include the name of the parent theme unless the themes have the same author
    This requirement was put in place in order to prevent theme names like “Twenty Sixteen Child” and to protect theme authors
  • Spell “WordPress” correctly in all public-facing text: all one word, with both an uppercase W and P

Top ↑

Options and Settings Options and Settings

  • Use the Customizer for implementing theme options
  • Save options in a single array
  • Don’t use transients for things they shouldn’t be used for, like storing theme options
  • Use sane defaults and don’t write default setting values to the database
  • Use edit_theme_options capability for determining user permission to edit options, rather than relying on a role (e.g. administrator), or a different capability (e.g. edit_themes, manage_options)

Top ↑

Plugins Plugins

  • Themes cannot include plugins
  • Themes mustn’t add plugin functionalities
  • Themes cannot require plugins to work
  • Themes may recommend plugins from WordPress.org
  • Themes may only use TGM Plugin Activation or similar libraries to recommend and install plugins that are hosted on WordPress.org (by using 'required' => false for each plugin)
  • Themes may include libraries such as option frameworks (these must pass the requirements)
  • Themes may recommend GPL compatible plugins that are not hosted on WordPress.org in the readme file or the themes information page but may not include a direct link to the download for security reasons. You can link to the product page for the recommended plugin, but not directly to the download file.

Top ↑

Screenshot Screenshot

  • The screenshot should be a reasonable representation of what the theme can look like
  • The screenshot may optionally show supported plugins, settings and templates
  • The screenshot should not be a logo or mockup
  • The screenshot should be no bigger than 1200 x 900px
  • The ratio of width to height should be 4:3
  • Screenshots are allowed to display only dummy text that doesn’t suggest/describe theme features, functionality, or statistics. If it looks like an advertisement, then it’s not allowed
  • Dummy text examples: Lorem ipsum (or similar generators), text that doesn’t describe your theme, company, service, or products

Top ↑

Privacy Privacy

  • Don’t ‘phone home’ without informed user consent. Make any collection of user data “opt-in” only and have a theme option that is set to disabled by default
  • No URL shorteners used in the theme (bit.ly, bit.do, goo.gl etc.)

Top ↑

Image guidelines Image guidelines

  • Images that show children with recognizable facial or body features are not permitted.

Top ↑

  • Theme URI is optional
  • If used, it must be about the theme we’re hosting on WordPress.org
  • If the URI is a demo site, the content must be about the theme itself and not test data
  • Using WordPress.org in the Theme URI is reserved for official themes.
  • Author URI is optional. If used it is required to link to a page or website about the author, author theme shop, or author project/development website
  • Themes may have a single footer credit link, which is restricted to the Theme URI or Author URI defined in style.css
  • Themes may also have an additional footer credit link pointing to WordPress.org

  • Your site needs to state explicitly that the products you’re selling/distributing (free and paid) are GPL compatible. It needs to be in an easy-to-find place for the reviewer and customers
  • Themes should not display “obtrusive” upselling
  • Themes are not allowed to have affiliate URLs or links

  • Themes can add a page under the Appearance menu using add_theme_page. If they need to have sub-pages (like for example documentation, FAQs, donation link etc), then they are allowed to use add_menu_page and add_submenu_page, provided they follow these requirements:
    • You can’t use add_theme_page and add_menu_page at the same time, choose one or the other.
    • You are allowed to create only one (1) main page using add_menu_page. The recommended maximum number of sub-menu pages (add_submenu_page) is three (3).
    • add_submenu_page must be used only on the page created using add_menu_page.
    • The $position (priority) parameter must be null or only occupy the spot above the Appearance page (59). Check the code example on how to set the correct priority.
    • If you recommend plugins via TGMPA, you are required to use the parent_slug configuration option (this should be the top-level page’s slug).
    • Core UI patterns must be used. You are not allowed to style the menu & submenu page links in any way. The admin color scheme must remain the same.
    • Use only monochromatic icons. It must account for the admin color scheme.
    • The title must be kept short and not include spam.
    • Child themes are allowed to add one extra sub-page or remove the parent’s pages and add their own.

Top ↑

Examples Examples

Unobtrusive upselling guidelines

The text domain should be generated from the theme slug.

Notifications such as admin notices must be dismissible.
This means that the notices should not only be closed, but hidden permanently when the “Dismiss” link is closed.

Only one sub-page in addition to the TGMPA plugin installation page is allowed under the Appearance section in the admin sidebar.

Only one link on the top level in the customizer is allowed. This must be done using the customizer API (no injecting via JavaScript). Example.
Further unobtrusive links are allowed in a separate section.

No options or panels/sections can be locked behind a paywall.

All settings in a theme must work.

As theme features for user social media

Social media links with icons settings are allowed.

The simpler Social media sharing links that uses sharer.php? or similar are allowed.

Social media “like” and “follow” buttons are not allowed.

Theme authors social media

Social media links are allowed.

Social media “like”, “follow” and “share” buttons are not allowed.

add_menu_page priority code example
function prefix_admin_menu() {
	$menus = $GLOBALS[ 'menu' ];
	$priority = array_filter( $menus, function( $item ) { 
		return 'themes.php' === $item[2];
	} );
	$priority = ! empty( $priority ) && 1 === count( $priority ) ? key( $priority ) - 1 : null;

	add_menu_page(
		__( 'Theme Name Title', 'textdomain' ),
		__( 'Theme Name', 'textdomain' ),

		'edit_theme_options',
		'theme-options.php',
		'',
		'dashicons-admin-customizer',
		$priority
	);
}
add_action( 'admin_menu', 'prefix_admin_menu' );

Top ↑

Stylesheets and Scripts Stylesheets and Scripts

  • No hard coding of script and style files
  • No minification of scripts or files unless you provide original files
  • Required to use core-bundled scripts rather than including their own version of that script. For example jQuery
  • Include all scripts and resources it uses rather than hot-linking. The exception to this is Google Fonts

Top ↑

Examples Examples

Enqueue stylesheets using wp_enqueue_style

The following example is not allowed:

<link type="text/css" rel="stylesheet" href="" />

The correct way would be to call wp_enqueue_style() from a function that is hooked on the wp_enqueue_scripts action:

add_action( 'wp_enqueue_scripts', 'theme_review_css' );

function theme_review_css() {
	wp_enqueue_style( 'theme-style', get_stylesheet_uri(), array(), '1.0.0', 'all' );
}
Printing internal styles using HTML tags directly in header.php is not allowed

The correct way would be to use a function that calls wp_add_inline_style and is hooked on the wp_enqueue_scriptsaction:

add_action( 'wp_enqueue_scripts', 'theme_review_styles' );

function theme_review_styles() {
	$custom_css = '
		.mycolor {
			background: red;
		}';
	wp_add_inline_style( 'theme-style', $custom_css );
}

That would print the content of the $custom_css variable inside style tags directly after the stylesheet with the handle ‘theme-style’ is printed in the head.

Enqueue scripts using wp_enqueue_script

The following example is not allowed:

echo get_template_directory_uri() . /js/theme-slider.js

The correct way would be to call wp_enqueue_style() from a function that is hooked on the wp_enqueue_scripts action:

add_action( 'wp_enqueue_scripts', 'theme_review_slider_options' );

function theme_review_slider_options() {
	wp_enqueue_script( 'theme-slider', get_template_directory_uri() . '/js/theme-slider.js', array( 'jquery' ), '1.0.0', false );
	wp_enqueue_script( 'theme-slider-init', get_template_directory_uri() . '/js/init.js', array( 'jquery', 'theme-slider' ), '1.0.0', false );

	// Get user options.
	$options = array();

	$options['autoplay']         = esc_attr( get_theme_mod( 'slider-autoplay', true ) );
	$options['navigation_style'] = esc_attr( get_theme_mod( 'nav-style', 'circles' ) );

	wp_localize_script( 'theme-slider-init', 'themeSliderOptions', $options );
}
Printing internal scripts using HTML tags directly in templates is not allowed

The correct way would be to use a function that calls wp_add_inline_script and is hooked on the wp_enqueue_scripts action:

add_action( 'wp_enqueue_scripts', 'theme_review_add_inline_script' );

function theme_review_add_inline_script() {
	wp_add_inline_script(
		'theme-review-script',
		'$(document).ready( function() {
			$(".selector").hide();
		}'
	);
}

That would print the hide() script inside script tags directly after the script with the handle ‘theme-review-script’ is printed in the head or footer.

What is considered an external resource

With external resources we mean any external resource including but not limited to: Scripts, styles, images, apis, videos or feeds.

You cannot publish your feed inside the theme, but you can link to it.

You cannot present and show an external video, but you can link to it.

You cannot load and present adverts, offers, or logos from your own website.

You cannot use an external api to use for example Google maps or Instagram.

Top ↑

Templates Templates

It’s worth noting we are working to automate a lot of the above requirements.

Now that you have read and made sure that your theme follows all the requirements, you are welcome to upload your theme.

Last updated: