WordPress 主题手册
WordPress 主题手册，介绍主题结构、模板、样式与发布流程。

Advanced Topics
Welcome to the advanced theme topics documentation. In this chapter, you will learn about some of the more complex features, techniques, and more that are not covered in previous chapters.
While this chapter is considered “advanced” it doesn’t mean you cannot learn something if you’re still getting started on your theme development journey. In many ways, the articles in this chapter are essential if you plan to distribute your theme to others, such as through the WordPress Theme Directory.
Navigating this chapter
Use the following links to locate a topic within this chapter. Each article covers a specific topic that is relevant to theme development, and you can explore each at your own pace.
Internationalization: Must-know techniques and tips to ensure your theme can be translated into any language.
Child Themes: Build a custom theme that extends an existing theme (i.e., parent theme) and requires less work.
Build Process: How to integrate with the 
@wordpress/scripts package to process and bundle your theme assets.
Privacy: Test the built-in WordPress privacy features and ensure your theme works with them.
Testing: How to run your theme through a suite of testing tools to make sure it works across a variety of environments.
Debugging: How to enable debugging in WordPress to ensure your theme is error free.
Security: A rundown of security best practices that your theme should be doing to defend against exploits.
Publishing Themes: The steps you need to take to publish your theme on WordPress.org or distribute to others.
This chapter also includes several other documents that are currently undergoing updates. These will eventually be updated or moved to more appropriate chapters:
Plugin API Hooks
UI Best Practices
JavaScript Best Practices

Core Concepts
Welcome to the Core Concepts documentation. The goal of this chapter is to introduce you to the foundational concepts necessary for creating your own WordPress block themes.
The focus of this chapter is to help you familiarize yourself with the basic theme structure and standard files like 
style.css, 
functions.php, and 
theme.json. Once you have these core concepts down, you can more comfortably dive into the later chapters in this handbook.
Navigating this chapter
Use the following links to locate a topic within this chapter. Each article is listed in the recommended reading order for those new to theme development. For those with existing experience creating themes, feel free to jump to the section you need:
Theme Structure: Walks through how a theme’s files and folders are structured following WordPress standards.
Main Stylesheet: Explains the importance of the theme’s 
style.css file and how to use it.
Custom Functionality: Dives into the theme’s functions file (
functions.php) and how you can use it to add your own functionality to a theme.
Templates: Introduces how WordPress’ block templates system works and provides pathways for deeper learning.
Including Assets: A guide on including CSS, JavaScript, images, and more in your themes.
Global Settings and Styles: Gives a basic overview of how the 
theme.json file works in themes with learning pathways to more detailed articles.

Credits
@ancawonka
@Anthonynotes
@atachibana
@austingunter
@bandonrandon
@utz119
@BFTrick
@BigActual
@bkozma
@boborchard
@Brainfestation
@celloexpressions
@charliehanger
@claymonk
@code_poet
@colorful-tones
@crondeau
@davidjlaietta
@daisyo
@digisavvy
@DrewAPicture
@enricchi
@esmi
@fabianapsimoes
@fiveo
@grapplerulrich
@greenshady
@hanni
@hlashbrooke
@hardeepasrani
@iandstewart
@jackreichert
@jacobmc
@JasonM4563
@jazzs3quence
@jboydston
@jcastaneda
@jcrglobalcaplaw
@JenniferBourn
@jerrysarcastic
@jgclarke
@jhoffm34
@jim-spencer
@jimdoran
@juhise
@juliekuehl
@kadamwhite
@kafleg
@karmatosed
@kenshino
@kenyasullivan
@kpdesign
@lettergrade
@linux-garage
@lizkaraffa
@lorax
@mariawoothemescom
@markel
@martydia
@missybunnie
@mt_Suzette
@nao
@NikV
@Otto42
@ozzyr
@philiparthurmoore
@poena
@PriscillaBiju
@rachelbaker
@Raporteur
@rahulsprajapati
@rclations
@rhauptman
@RussE
@ryanr14
@SagarGurnani
@samuelsidler
@sarahovenall
@semblance_er
@sewmyheadon
@SeReedMedia
@sheebaabraham
@siobhan
@stubbs123
@suastex
@sushil-adhikari
@Techdoode
@thepixelista
@topher1kenobe
@TJNowell
@xfrontend
@viniciuslourenco
@vrm

Features
Welcome to the Features documentation. In this chapter, you will learn about various features supported by the WordPress block theming system.
This chapter does not have a singular focus. Instead, it offers information on several different topics that will help you work with more advanced features, stepping beyond the basics that you learned in Global Settings and Styles and Templates.
Navigating this chapter
Use the following links to locate a topic within this chapter. Each article covers a specific feature related to building block themes, and you can explore each at your own pace.
Block Style Variations: Build custom block style variations (aka: block styles) for your users to select.
Block Stylesheets: Register per-block stylesheets to compartmentalize your custom CSS and make your theme load faster.
Block Variations: Register variations on the default settings for a block and let your users add them via the interface.

Getting Started
Welcome to the Getting Started documentation. This chapter is primarily intended to introduce you to navigating the handbook itself, learning what WordPress themes are, and helping you get your first WordPress block theme up and running.
While this chapter primarily focuses on readers who are new to theme development altogether, it is also meant as a resource for seasoned themers who are learning how to build block themes for the first time.
Navigating this chapter
Use the following links to locate a topic within this chapter. Each article will walk you through the steps of navigating this handbook and getting a base understanding of how WordPress themes work:
What Is a Theme?: An introduction to what WordPress themes are and an explanation of the various types of themes.
Who Is This Handbook For?: Explains who this handbook is for and why you might want to read it.
Reading This Handbook: Offers learning pathways for navigating the handbook based on skill level and provides an introduction on reading code samples.
Tools and Setup: Gives an overview of all the tools that are required to create WordPress themes and offers recommendations on other useful apps and programs to consider.
Quick-Start Guide: A step-by-step guide for getting your first basic theme up and running for those new to block theme development.

Global Settings and Styles (theme.json)
Welcome to the Global Settings and Styles documentation. In this chapter you will learn everything you need to know about configuring settings, styles, and more via your theme’s 
theme.json file.
theme.json is a foundational piece of block theming. While it is not a strictly required file, you will need to work with it for nearly any theme project. It is useful for everything from configuring colors to defining default typography settings to applying front-end styles to your theme.
Navigating this chapter
Use the below links to find the topic you are looking for in this chapter. Each section of the chapter is set up to offer a straightforward learning path toward learning the ins-and-outs of 
theme.json for first-time themers. But if you are already familiar with the foundational concepts, feel free to skip ahead to the topic you want to learn more about.
Introduction to 
theme.json: A walkthrough of setting up your 
theme.json file, introducing you to the foundational concepts for configuring global settings and styles for your theme.
Settings: Documentation for each of the standard and custom settings that you can configure via 
theme.json. Sub-pages document every available setting.
Styles: Learn how to use the standard design system to apply styles through 
theme.json, which also integrate with the user interface.
Custom Templates: How to register custom post, page, and CPT (custom post type) templates for your theme.
Template Parts: How to register custom template parts that can be reused across your theme.
Patterns: How to bundle patterns from the official patterns repository with your theme.
Style Variations: Documentation on creating custom 
theme.json style variations, giving your users alternative designs to choose from.

Theme Handbook
Welcome to the WordPress Theme Developer Handbook, your resource for learning all about the exciting world of WordPress themes.
The Theme Developer Handbook is a repository for all things WordPress themes. Whether you’re new to WordPress themes, or you’re an experienced theme developer, you should be able to find the answer to many of your theme-related questions right here.
In this handbook, you can learn how to build block themes or classic themes.
A block theme is a new theme that you can use from WordPress version 5.9. It is built mainly using HTML and a theme configuration file. The block theme is composed entirely of blocks, allowing you to edit all parts of your site in the Site Editor.
A classic theme is the original theme, without version limitations, that primarily uses PHP, JavaScript and CSS. Classic themes take advantage of WordPress PHP functions, hooks and filters.
If you’re new to developing WordPress themes, start with section 1, where you can find out what a theme is, learn about WordPress’ license, and set up your development environment.
Once you’re through the introduction, continue with the Core Concepts section.
It is recommended to read through both the block theme section and the classic theme sections. This will give you an understanding of the differences between the two types of themes, and help you choose what type of theme to build.
If you’ve got to grips with the basics of themes, check out the Advanced Theme Topics to learn about child themes, best UI practices, theme testing and more.
Once you’ve got your theme ready for the world, the final section will cover releasing your theme, teaching you some best practices for theme distribution, and for getting it ready for the WordPress.org theme directory.
The WordPress Theme Developer Handbook is created by the WordPress community, for the WordPress community. We are always looking for more contributors; if you’re interested stop by the docs team blog to find out more about getting involved.

Patterns
Patterns are one of the most useful tools for theme development, allowing you to reuse groups of blocks across a wide variety of scenarios. Over time, you will likely use patterns more than any other theme feature available in WordPress.
In this chapter, you will learn what patterns are and dive into the various use cases where you will apply them in your themes. This will include everything from providing insertable layouts to your theme users to running PHP for loading assets and even more.
Navigating this chapter
Use the following links to locate a specific topic within this chapter. It’s best to read them in order, but if you are already familiar with the basic tenets of pattern development, feel free to jump to the topic that you’re looking for.
Introduction to Patterns: Provides an overview of what patterns are and how they work, giving you a foundation for later articles in the chapter.
Registering Patterns: A guide on registering/unregistering patterns and pattern categories for your theme.
Using PHP in Patterns: How and why to use PHP in your themes, including practical applications like internationalizing text and including media.
Usage in Templates: How to include patterns in templates and why you should use them over templates in many cases.
Block Type Patterns: A walkthrough of creating block-specific patterns that offer a more elegant experience for your theme users.
Starter Patterns: Building custom patterns as starting points for creating starting points for your theme users to build their pages and templates.
Patterns and Block Locking: How to use the Block Locking API to curate the editing experience for your theme users.

Releasing Your Theme
This section covers the requirements and submission process for releasing your theme into the WordPress Theme Directory. If you’ve followed the instructions in this handbook, your theme is almost ready for release into the directory.
The first requirement to releasing your theme is to make sure you have – at a minimum – the required theme files before submitting your theme for review.
Once you’ve confirmed the required theme files, thorough testing of the theme – including content – must be completed. Following the theme review guidelines will help ensure acceptance of your theme.
After completing everything above, having the proper documentation is the final step before submitting your theme for approval. After submitting your theme for review, the theme reviewer may request other changes to your theme.
Important Notices
Themes that have 3 or more distinct issues may be closed as not-approved. Theme authors are encouraged to review the Theme Review Guidelines.
“How to do a review (Draft)” is another practical guide to understand the review process in-depth.
First Two Checks
1. Commonly missed requirements
Here are some of the commonly missed requirements at the initial review. Themes with incomplete requirements may be closed as not-approved.
Themes must be compatible with the GNU General Public License. GPLv2 or later is strongly recommended.
Themes are not allowed to include plugins and non-design related functionalities such as forms. Anything that will be deleted when user switches a theme should not be included.
Shortcodes, custom post types, and custom blocks are not allowed in themes.
2. Testing your theme with Theme Check Plugin
Theme Check plugin is an easy way to test your theme and ensure it’s up to spec with the latest theme review standards. Learn more about Theme Check Plugin.

Templates
Welcome to the Templates documentation. In this chapter you will learn how the WordPress block template system works, how to build custom templates and parts, and include them in your theme.
Templates are one of the core concepts of building websites, representing the underlying structure that presents your content in the browser. In many ways, they are the most important feature of developing WordPress themes.
Navigating this chapter
Use the below links to find the topic you are looking for in this chapter. Each section of the chapter is set up to offer a straightforward learning path toward learning how to build templates for those building their first theme. But if you are already familiar with the foundational concepts, feel free to skip ahead to the topic you want to learn more about.
Introduction to Templates: An overview of what templating is, how the templating system in WordPress works, and a look at the relationship between the template hierarchy, templates, and template parts.
Templates: How to build custom templates and include them in your WordPress theme.
Template Hierarchy: How WordPress decides which template to use based on the page the user is viewing.
Template Parts: How to build template parts and insert them into top-level templates.

Build Process
A build process is a method of converting source code files into a final build/production version that can be read by the computer. In particular, themes will most often be minifying or converting source code into CSS or JavaScript so that they can be read by the browser.
When creating a WordPress theme, you may find yourself in need of a build process to handle more complex projects. There are many systems to choose from, and you can use whatever you prefer. But WordPress also offers a standard package that you can be assured is continually updated and should cover most of your needs.
In this article, you will learn how to integrate with the 
@wordpress/scripts package to handle your theme’s build process.
Prerequisites
Most of WordPress theme development is pretty much plug and play. You just need a code editor and an install of WordPress in some type of development environment as outlined in Tools and Setup. But to work with a build process, there are some other requirements:
You need to have Node.js and npm installed on your local machine.
A basic understanding of webpack is also highly recommended.
Some familiarity with the 
@wordpress/scripts package (read Getting started with wp-scripts in the Block Editor Handbook).
These are more advanced tools than what is normally required to build themes, but they are necessary if you want to work with the standard WordPress build process.
Setting up your files and folders
The 
@wordpress/scripts package was originally created for block development, but it evolved to also work with themes over time. By default, it expects that development files live in the 
/src folder and will output build files in the 
/build folder. Because most theme authors utilize a custom system for working with assets, this guide will show you how to do that.
For the examples that follow, you will use this structure within your theme folder:
public/
resources/
js/
editor.js
scss/
editor.scss
screen.scss
package.json
webpack.config.js
Installing the WordPress scripts package
Once you have your files and folders set up, you need to install the correct packages on your local machine.
First, open your theme’s 
package.json file and add the following code:
{
	"name": "your-project-name",
	"scripts": {
		"start": "wp-scripts start --webpack-src-dir=resources --output-path=public",
		"build": "wp-scripts build --webpack-src-dir=resources --output-path=public"
	}
}
The 
@wordpress/scripts package has several other available scripts that you can add, but you will definitely need 
start and 
build.
Now open your command line tool on your computer, navigate to your theme folder, and input the following command:
npm install @wordpress/scripts path webpack-remove-empty-scripts --save-dev
That command installs three packages:
@wordpress/scripts
path
webpack-remove-empty-scripts
The latter two are third-party packages, but they are useful for integrating with webpack in the next step.
Configuring webpack
The 
@wordpress/scripts package is built on top of webpack. If you were building a block, everything would already be in place for you. However, because you are building a theme, you need to overwrite some of the default configuration of the 
@wordpress/scripts package with your own.
That’s where your theme’s custom 
webpack.config.js file comes in. There two primary things you need to configure:
The entry points for your custom CSS and JavaScript files (those in the code below correspond to the file structure in this article).
The 
webpack-remove-empty-scripts plugin so that there are no leftover 
.js files mapped to your CSS.
Add the following code to your 
webpack.config.js file:
// WordPress webpack config.
const defaultConfig = require( '@wordpress/scripts/config/webpack.config' );
// Plugins.
const RemoveEmptyScriptsPlugin = require( 'webpack-remove-empty-scripts' );
// Utilities.
const path = require( 'path' );
// Add any new entry points by extending the webpack config.
module.exports = {
	...defaultConfig,
	...{
		entry: {
			'js/editor':  path.resolve( process.cwd(), 'resources/js',   'editor.js'   ),
			'css/screen': path.resolve( process.cwd(), 'resources/scss', 'screen.scss' ),
			'css/editor': path.resolve( process.cwd(), 'resources/scss', 'editor.scss' ),
		},
		plugins: [
			// Include WP's plugin config.
			...defaultConfig.plugins,
			// Removes the empty `.js` files generated by webpack but
			// sets it after WP has generated its `*.asset.php` file.
			new RemoveEmptyScriptsPlugin( {
				stage: RemoveEmptyScriptsPlugin.STAGE_AFTER_PROCESS_PLUGINS
			} )
		]
	}
};
Using the WordPress scripts package
To use the WordPress scripts package to process your assets, you can run one of two commands in your command line tool:
start: Builds the development version of your files and activates “watch” mode, which will process any code changes while enabled.
build: Builds the production version of your files.
Now open your command line tool and run the 
start command:
npm run start
It should automatically process your files from the 
/resources folder and place them in the 
/public folder with this structure:
public/
js/
editor.js
editor.asset.php
scss/
editor.scss
editor.asset.php
screen.scss
screen.asset.php
You’ll now see new 
*.asset.php files generated for each of your CSS and JavaScript files. These will contain metadata about each asset file that you can use when loading your files. This is covered in the “Loading scripts and styles” section below.
To disable the 
start command, type 
Ctrl + C (on either Windows or Mac) of your command line tool.
Once you’re ready to do a final production build of your files, run this command in your command line tool:
npm run build
Loading scripts and styles
The methods for loading scripts and styles are already covered in depth in the Including Assets documentation in this handbook. You should already be familiar with how to do this before proceeding with the next steps.
The documentation below is primarily geared towards teaching you how the 
*.asset.php file is generated for each asset. In each file, you will see an array that looks similar to the following snippet:
<?php return array('dependencies' => array('wp-block-editor'), 'version' => '2eae4c519afeff2a8c77');
In particular, the array will have two pieces of metadata that you can use in any 
wp_enqueue_*() functions:
dependencies: An array of dependencies that your script/style rely on.
version: A version number that you can use for cache busting.
Because the file returns the array, you can use PHP’s 
include to assign the array to a variable in your code. The following example shows getting the array for the 
screen.asset.php file:
$asset = include get_theme_file_path( 'public/css/screen.asset.php' );
// Returns: array( 'dependencies' => array(), 'version' => '0000' );
When loading a script or style using either 
wp_enqueue_script() or 
wp_enqueue_style(), you can pass 
$asset['dependencies'] and 
$asset['version'] to the corresponding parameters in the functions.
Try adding the following code to your theme’s 
functions.php file to load the assets that you’ve previously defined:
// Load front-end assets.
add_action( 'wp_enqueue_scripts', 'themeslug_assets' );
function themeslug_assets() {
	$asset = include get_theme_file_path( 'public/css/screen.asset.php' );
	wp_enqueue_style(
		'themeslug-style',
		get_theme_file_uri( 'public/css/screen.css' ),
		$asset['dependencies'],
		$asset['version']
	);
}
// Load editor stylesheets.
add_action( 'after_setup_theme', 'themeslug_editor_styles' );
function themeslug_editor_styles() {
	add_editor_style( [
		get_theme_file_uri( 'public/css/screen.css' )
	] );
}
// Load editor scripts.
add_action( 'enqueue_block_editor_assets', 'themeslug_editor_assets' );
function themeslug_editor_assets() {
	$script_asset = include get_theme_file_path( 'public/js/editor.asset.php'  );
	$style_asset  = include get_theme_file_path( 'public/css/editor.asset.php' );
	wp_enqueue_script(
		'themeslug-editor',
		get_theme_file_uri( 'public/js/editor.js' ),
		$script_asset['dependencies'],
		$script_asset['version'],
		true
	);
	wp_enqueue_style(
		'themeslug-editor',
		get_theme_file_uri( 'public/css/editor.css' ),
		$style_asset['dependencies'],
		$style_asset['version']
	);
}

Debugging
Debugging is the practice of finding and fixing errors in any software that you build. And it is an essential part of WordPress theme development, regardless of whether you are building a block or classic theme.
WordPress provides some tools out of the box, but there are also plugins that you can use to enhance the experience. You’ll learn about some of these methods in this article, but you should also study the Debugging in WordPress documentation in the Common APIs handbook.
Debugging constants
When creating themes from within a development environment, you should always enable debugging to ensure that your theme is not creating notices or errors. WordPress offers several constants, which you can set in your installation’s 
wp-config.php file.
If you open the 
wp-config.php file, scroll down until you locate this code:
/**
 * For developers: WordPress debugging mode.
 *
 * Change this to true to enable the display of notices during development.
 * It is strongly recommended that plugin and theme developers use WP_DEBUG
 * in their development environments.
 *
 * For information on other constants that can be used for debugging,
 * visit the documentation.
 *
 * @link https://wordpress.org/documentation/article/debugging-in-wordpress/
 */
define( 'WP_DEBUG', false );
This is where you will configure any debugging constants outlined in the sections below.
WP_DEBUG
The 
WP_DEBUG constant is the only one defined in a default WordPress installation’s 
wp-config.php file. In a standard install, it is set to 
false, but it is set to 
true if you are running a development copy of WordPress.
The 
WP_DEBUG PHP constant is used to trigger the built-in “debug” mode on your WordPress installation. This allows you to view errors in your theme. It should be used in conjunction with all of the other debugging constants listed in the next sections.
You should see this line in your 
wp-config.php file:
define( 'WP_DEBUG', false );
To enable debugging, make sure it is set to 
true, as shown here:
define( 'WP_DEBUG', true );
WP_DISABLE_FATAL_ERROR_HANDLER
WordPress 5.2 introduced a fatal error handler to ensure that users do not get locked out of their site when a theme or plugin causes a fatal error. This is a great feature in production/live sites. But it can be problematic in development, preventing you from fully diagnosing errors.
For this reason, in development, you should disable this to make sure things are broken until you can fix them. Define this constant in your 
wp-config.php file:
define( 'WP_DISABLE_FATAL_ERROR_HANDLER', true );
WP_DEBUG_DISPLAY
WP_DEBUG_DISPLAY is used to control whether debug messages display within the HTML of your WordPress site. By default, when 
WP_DEBUG is enabled, debugging messages will be shown on the screen. So, you can safely not define 
WP_DEBUG_DISPLAY during development.
If you want to disable on-screen debugging messages, you can set 
WP_DEBUG_DISPLAY to 
false in your  
wp-config.php file:
define( 'WP_DEBUG_DISPLAY', false );
WP_DEBUG_LOG
The 
WP_DEBUG_LOG constant is an optional feature that you can set to log errors to a 
debug.log file in your site’s 
/wp-content directory. By default, this is disabled.
Generally, if you turn off on-screen debugging messages via 
WP_DEBUG_DISPLAY, then you will want to opt for storing these messages in the debug log.
To enable logging, define the 
WP_DEBUG_LOG constant as 
true in your 
wp-config.php file:
define( 'WP_DEBUG_LOG', true );
Plugins
There are several plugins that are helpful when debugging your theme. Each is hosted in the WordPress Plugin Directory:
Debug Bar: Provides a central location for debugging in your WordPress toolbar.
Query Monitor: Enables debugging of database queries, PHP errors, hooks and actions, block editor blocks, enqueued scripts and stylesheets, HTTP API calls, and more.
Log Deprecated Notices: Logs incorrect and deprecated function and file usages in your theme.

Internationalization
Internationalization is the process of developing your theme in such a way that its custom text can be translated into other languages. The term is often abbreviated as “i18n” because there are 18 letters between the “i” and “n,” the first and last letters.
In this article, you will learn how to internationalize your WordPress themes and why it is important.
Why internationalization is important
WordPress is used all over the world, in countries where your native language is not used. The strings in the WordPress themes need to be coded in a special way so that they can be easily translated into other languages.
Even if you yourself do not know multiple languages, internationalization leaves the door open for translators to localize the text. Localization is the process of taking internationalized text and translating it for a specific language and locale. It is often abbreviated as “l10n.”
WordPress has a built-in translation system that allows localizing a theme without having to modify the source code of the theme itself. This is important because it means that users can keep up with theme updates while using their preferred translation.
You can certainly build a WordPress theme without internationalization, particularly if it’s for a site that you know will never be translated. But in most cases, it is considered standard practice to internationalize all of your theme’s text. For one, it means that it can be used by people in other languages, giving you a wider audience. And it is also a requirement when submitting a theme to the official Theme Directory.
How to internationalize your theme
Getting your text domain
The text domain is a unique identifier, allowing WordPress to distinguish between all of the loaded translations. That means that you need something unique for your theme so that WordPress will recognize translations that belong to it.
The text domain is used in three different places in your theme:
In the 
style.css file header.
As an argument in internationalization functions.
As an argument when loading translations (optional for themes submitted to the WordPress Theme Directory).
Your theme’s text domain should always match your theme slug, as described in the Reading this handbook documentation. This is a central component in making sure your theme is ready for translation.
The de facto standard (and requirement if submitting your theme to the WordPress Theme Directory) is to use the kebab-case version of your theme name. This means that it should:
Use all lowercase letters.
Have no spaces.
Hyphenate when there are multiple words.
So if your theme’s name is 
Fabled Sunset, your text domain should be 
fabled-sunset.
Defining your text domain
As described in the Main Stylesheet documentation, you can configure several important pieces of metadata about your theme via the 
style.css file header. In particular, there are two meta values you can define related to internationalization:
Text Domain: The string used for the text domain for translations.
Domain Path: A relative path to where theme translations are stored. WordPress uses this field when the theme is disabled to detect translations. Defaults to 
/languages if not defined.
For translations to work correctly, you must at least define the 
Text Domain field, which should be your theme’s slug.
Let’s imagine your theme name is “Fabled Sunset” and you want translations stored in your theme’s 
/assets/lang folder. Your theme’s 
style.css should define these fields like so:
/**
 * Theme Name:        Fabled Sunset
 * ...
 * Text Domain:       fabled-sunset
 * Domain Path:       /assets/lang
 * ...
 */
It’s important to add this metadata to your 
style.css file because WordPress uses it even when the theme is not enabled (for example, when viewing all themes from the Appearance > Themes screen in the admin).
Wrapping text with internationalization functions
For text in your theme to be easily translated in your theme, it must be wrapped in an internationalization function instead of hardcoded. The available internationalization functions are listed in the Common APIs handbook.
In a typical HTML-based webpage, you would add plain text strings. For example, take a look at this example heading:
<h2>Latest Posts</h2>
Because it is merely plain text, it cannot be translated into other languages without directly modifying the code.
Let’s wrap that text in the 
_e() internationalization function, which tells WordPress that the text inside should be available for translation and echoed (printed to the screen):
<h2><?php _e( 'Latest Posts', 'themeslug' ); ?></h2>
Now users can add translations for your theme without touching the code.
As you may have noticed, the 
_e() function accepted a second parameter of 
themeslug. This should be replaced with your text domain.
There are many other internationalization functions that you will use, and you will learn about them later. For now, the idea is to introduce you to the basic concept.
Because internationalized text is technically a PHP variable, it means that it can be exploited and become a security vulnerability. You should always use the translate-and-escape functions when possible. Otherwise, be sure to wrap them in an escaping function when outputting, as described in the Security documentation.
Loading translations
For themes hosted in the WordPress Theme Directory, you do not need to load translations. WordPress automatically checks the 
wp-content/languages directory in a user’s install and will download translations from the Translating WordPress site. All translations can be handled there, and you don’t have to worry about storing or loading them from your theme.
Translation in WordPress are saved in 
.po (human readable) and 
.mo (machine readable) files. The 
.mo files are the ones actually used by WordPress.
WordPress will look in two places for translation files based on the user’s locale defined for the site:
wp-content/themes/your-theme/{domain-path}/{locale}.mo
wp-content/languages/themes/{textdomain}-{locale}.mo
To load translation files from your theme, you must use one of two functions:
load_theme_textdomain()
load_child_theme_textdomain() (if building a child theme)
Let’s take a look at the 
load_theme_textdomain() function signature (it’s the same for both functions):
load_theme_textdomain(
	string $domain, 
	string|false $path = false 
): bool
The function accepts two parameters:
$domain: This should be the text domain for your theme as defined in 
style.css.
$path: This must be a full directory path to the location of translations in your theme. If left undefined, WordPress will fall back to your theme’s root folder.
Using the same example “Fabled Sunset” theme described earlier with translations stored in the 
/assets/lang folder, let’s try loading translations from the theme.
Add this code to your theme’s 
functions.php file:
add_action( 'after_setup_theme', 'themeslug_load_textdomain' );
function themeslug_load_textdomain() {
	load_theme_textdomain(
		'fabled-sunset',
		get_parent_theme_file_path( 'assets/lang' )
	);
}
The above call to 
load_theme_textdomain() was executed on the 
after_setup_theme action hook, which fires immediately after the theme’s 
functions.php is loaded.
If you were building a child theme, your 
functions.php code would instead look like this:
add_action( 'after_setup_theme', 'themeslug_load_textdomain' );
function themeslug_load_textdomain() {
	load_child_theme_textdomain(
		'fabled-sunset',
		get_theme_file_path( 'assets/lang' )
	);
}
Resources
Internationalization is a large topic and is covered in full in the Internationalization chapter of the Common APIs handbook. What you learn there will apply to both theme and plugin development.
WordPress has many internationalization functions for you to use when wrapping text. Which one to use will be context-specific. Take the time to study each function so that you will know when to use it. The Internationalization Guidelines will set you down the correct path.

JavaScript Best Practices
Many themes use JavaScript to provide interactivity, animation or other enhancements. These best practices will help ensure your code works efficiently and does not cause conflicts with your content or plugins.
Use Included Libraries
There are many useful JavaScript libraries you may want to include when building your theme. Did you know that WordPress comes bundled with dozens of popular libraries? Check out this list of default scripts included with WordPress.
A common mistake made by beginning theme and plugin developers is to bundle their theme or plugin with their own version of the library. This may conflict with other plugins that enqueue the version bundled with WordPress. As a best practice, make your theme compatible with the version of your favorite library included with WordPress.
Do not try to use your own version of a JavaScript library that is already bundled with WordPress. Doing so may break core functionality and conflict with plugins.
If you feel you MUST replace the WordPress version with one of your own… well… the answer is still: don’t do it.  The versions of JavaScript libraries used by WordPress may include custom tweaks that WordPress needs to operate.  Any time you override these libraries, you risk breaking your WordPress instance. Moreover, plugins created by other authors should be written to be compatible with WordPress’s version of these libraries as well. Adding your own version may (and often does!) conflict with plugins.
Standard JavaScript
Javascript is growing in popularity for web developers, and it’s being used to accomplish for a variety of tasks. Here are some best practices to use when writing your JavaScript
Avoid Global Variables
Keep your JavaScript unobtrusive
Use closures and the module pattern
Stick to a coding style. Use The WordPress Javascript Coding Standard.
Validate and Lint Your Code – ESLint.com
Ensure your site still works without JavaScript first – then add JavaScript to provide additional capabilities. This is a form of Progressive Enhancement.
Lazy load assets that aren’t immediately required.
Don’t use jQuery if you don’t need to — There’s a great site that shows you how to do some common tasks with plain old JavaScript – you might not need jQuery
jQuery
Including jQuery in your theme
jQuery is a popular JavaScript library to make working with JavaScript easier and more reliable across browsers. If you use jQuery, be sure to follow the handbook guidelines on including JavaScript. Giving your theme’s enqueued .js files a dependency array of 
array( 'jquery' ) ensures that the jQuery script has been downloaded and loaded before your theme’s code.
Using $
Because the copy of jQuery included in WordPress loads in 
noConflict() mode, use this wrapper code in your theme’s .js files to map “$” to “jQuery”:
( function( $ ) {
// Your code goes here
} )( jQuery );
This wrapper (called an Immediately Invoked Function Expression, or IIFE) lets you pass in a variable—jQuery—on the bottom line, and give it the name “$” internally. Within this wrapper you may use 
$ to select elements as normal.
Selectors
Every time you select an element with jQuery, it performs a query through your document’s markup. These queries are very fast, but they do take time—you can make your site respond faster by re-using your jQuery objects instead of using a new query. So instead of repeating selectors:
// Anti-pattern
$('.post img').addClass('theme-image');
$('.post img').on('click', function() { ... });
it is recommended to cache your selectors so you can re-use the returned element without having to repeat the lookup process:
var $postImage = $('.post img');
// All image tags within posts can now be accessed through $postImage
$postImage.addClass('theme-image');
$postImage.on('click', function() { ... });
Event Handling
When you use jQuery methods like 
.bind or 
.click, jQuery creates a new browser event object to handle processing the requested event. Each new event created takes a small amount of memory, but the amount of memory required goes up the more events you bind. If you have a page with a hundred anchor tags and wanted to fire a 
logClick event handler whenever a user clicked a link, it is very easy to write code like this:
// Anti-pattern
$('a').click( logClick );
This works, but under the hood you have asked jQuery to create a new event handler for every link on your page.
Event delegation is a way to accomplish the same effect with less overhead. Because events in jQuery “bubble”—that is, a click event will fire on a link, then on the link’s surrounding 
<p> tag, then on the 
div container, and so on up to the 
document object itself—we can put a single event handler higher up in the page structure, and still catch the click events for all of those links:
// Bind one handler at the document level, which is triggered
// whenever there is a "click" event originating from an "a" tag
$(document).on('click', 'a', logClick);

Plugin API Hooks
A theme should work well with WordPress plugins. Plugins add functionality by using actions and filters, which are collectively called hooks (see Plugin API for more information).
Most hooks are executed internally by WordPress, so your theme does not need special tags for them to work. However, a few hooks need to be included in your theme templates. These hooks are fired by special Template Tags:
wp_head()
:   Goes at the end of the  element of a theme’s header.php template file.
wp_body_open()
:   Goes at the begining of the  element of a theme’s header.php template file.
wp_footer()
:   Goes in footer.php, just before the closing  tag.
wp_meta()
:   Typically goes in the Meta section of a Theme’s menu or sidebar.
comment_form()
:   Goes in comments.php directly before the file’s closing tag ().
Take a look at a core theme’s templates for examples of how these hooks are used.

Privacy
WordPress 4.9.6 introduced several tools to help sites meet the requirements of the European Union’s new GDPR (General Data Protection Regulation) and other potential laws across the world. This article details what theme authors need to know about compatibility with the features.
For the most part, this should not directly impact themes, but you should make sure that nothing in your theme’s design or functionality conflicts with these features.
Privacy Policy page
WordPress lets users select a privacy policy page via the Settings > Privacy screen in the admin. For newly-created WordPress installs (since version 4.9.6), a privacy policy page is automatically created with a draft status.
Linking to the Privacy Policy page
If you need to manually link to the Privacy Policy page on a site, WordPress provides a few functions for getting or outputting the URL or link:
get_privacy_policy_url(): Retrieves the URL to the Privacy Policy page.
the_privacy_policy_link(): Displays the Privacy Policy page link with formatting, when applicable.
get_the_privacy_policy_link(): Returns the Privacy Policy page link with formatting, when applicable.
The following example will display the privacy policy link surrounded by a 
<div> element:
<?php the_privacy_policy_link( '<div>', '</div>' ); ?>
Privacy Policy page template
While it is generally unnecessary for most themes, you can add a custom Privacy Policy template to customize the output of the page. This is an optional template:
Block Themes: 
templates/privacy-policy.html
Classic Themes: 
privacy-policy.php
If you decide to create a custom template, make sure that you output the page’s content using the appropriate block or function:
Block Themes: Post Content block
Classic Themes: 
the_content() function
This ensures that the user’s Privacy Policy content will be correctly displayed on the front end of the site.
Comment cookies
When a logged out user comments on a post, they are asked for their name, email, and website. This information is stored locally in the commenter’s browser for two purposes:
When they leave another comment on the site, their name, email, and website will be pre-populated into the respective fields.
If their comment is held for moderation, they can return to that post and remove the comment before it is approved.
The information stored in this cookie is for convenience and is not essential. Therefore, the user needs to be given the choice to opt in or opt out of the storage of this data. For this reason, WordPress outputs a checkbox in the comment form that allows commenters to opt-in to storing this data in the cookie. This checkbox will be unchecked by default, as opt-in is an action the user must explicitly approve.
The new checkbox field is automatically added to comment forms displayed using the Comment Form block (block themes) or the 
comment_form() function (classic themes).
While most themes will not require any action, it is recommended that you double check that the input and label does not require CSS adjustments in custom themes.

Testing
Whether you are planning to share your WordPress theme with a broad audience or aiming for a specific platform, this article will help you get your theme ready for release. It focuses on general theme testing to ensure your theme’s quality and compatibility across various environments.
Expanding on the principles from previous sections, this article covers things like code quality, compatibility, and responsiveness. By the end, your theme will be ready to use on a live site.
Testing environment
When building your theme, it is good practice to test from within some type of development environment. In this section, you will get an overview of a couple of methods that you can explore further on your own.
Local environment
A local development environment provides a controlled space for developing and testing your theme without impacting your live site. Some of the available options are listed in the Tools and Setup documentation.
When developing locally, you should always have debugging enabled. Check out the Debugging documentation for information on debugging techniques and tools that will help you handle errors and optimize your theme development process.
WordPress Playground
WordPress Playground is another option for testing. It operates entirely in the browser, providing a controlled space for testing.
Here is a look at the default Twenty Twenty-Four theme running in Playground:
To become more familiar with using this platform, please refer to the official WordPress Playground documentation.
Theme Unit Test Data
When developing a WordPress theme, ensuring that it can handle a variety of content is fundamental. To assist in this process, WordPress provides a set of Theme Unit Test Data via an importable XML file. To be clear, this is just one part of a larger theme testing process.
The test data is a collection of posts, pages, comments, and media that you can import into your WordPress installation. By testing with this data, you can check how your theme handles edge cases, such as extremely long titles, images of varying sizes, nested comments, and a mix of HTML elements.
To test your theme with the Theme Unit Test Data, you need to:
Download the data: Get the latest version from the GitHub repository.
Import the data: Use the WordPress Importer tool to import the data into your WordPress environment.
Once you’ve imported the content into your test install, examine how each piece of content is displayed. Pay special attention to areas where your theme might be prone to issues. Also be sure to view your theme on various devices and screen sizes to make sure the content is displayed as expected.
Tools and resources
When testing your theme, it is important to use tools that will check every aspect of your theme for potential issues.
The Theme Check Plugin evaluates your theme against the Theme Review Guidelines before submitting to the official directory. Even if not submitting to the directory, it can also be useful for making sure your theme meets some baseline standards.
Some other WordPress plugins you should include in your testing suite are:
Debug Bar: Adds an admin bar to your WordPress admin and provides a central location for debugging.
Query Monitor: Allows debugging of database queries, API requests, and AJAX used to generate theme pages and functionality.
Log Deprecated Notices: Logs incorrect function usage, deprecated file usage, and deprecated function usage in your theme.
Monster Widget: Consolidates the core WordPress widgets into a single widget, making it easier to test them all at once (classic themes only).
For effective cross-browser compatibility testing of block themes, it is important to use the developer tools available with modern browsers, such as:
Firefox: Developer Edition
Chrome DevTools
Functional testing
Testing your theme’s compatibility with basic WordPress features is necessary. This step ensures that your theme not only looks good but also works with WordPress’s core functionality.
Testing basic WordPress features
It is important that your theme works with core features and behaves as expected. The following are some of the basic features to test:
Posts and pages:
Create a variety of posts and pages using the block editor. Experiment with different types of content, including text, images, and videos.
Pay attention to how all standard blocks (paragraphs, images, headings, lists, etc.) are displayed. Are they aligning correctly? Is the spacing consistent?
Block settings:
Test the settings of each block to ensure they function as intended. For instance, when you change the alignment of an image or the color of a heading, does the theme reflect these changes accurately?
Responsiveness:
Check how these elements adapt to different screen sizes. Ensure the layout remains intuitive and user-friendly on mobile devices.
Comments:
Look at the comments section of your posts. Are comments and replies displaying correctly?
Ensure that threaded comments are displayed in a nested format, making it easy to follow conversations.
Test the comment block in the block editor. Does it integrate well with your theme? Are there styling or functionality issues?
If you’re building a block theme, as this handbook recommends, you should also test these features:
Site Editor: Test the Site Editor and make sure that you can edit templates and template parts like headers and footers.
Styles interface: Check the functionality of the Styles interface, where you can customize colors, typography, and layout settings that apply across your theme.
Navigation block: Pay special attention to the Navigation block. Test its responsiveness, the ease of adding menu items, sub-menu functionality, and alignment options.
Template editing: Explore the Template Editor for creating and modifying templates for specific posts or pages.
Accessibility testing
Ensuring accessibility is a key aspect of responsible theme development.
You should strive to make sure your theme meets the WordPress Accessibility Guidelines. This includes aspects like keyboard navigation, screen reader compatibility, and proper use of ARIA roles.
Tools like aXe and WAVE are invaluable in identifying potential accessibility issues. Regularly use them during development to find and fix any problems. This proactive approach helps in creating a theme that is accessible to all users, regardless of how they navigate the web.
Performance testing
You should also ensure that your theme is not unnecessarily loading too many resources. For this, you can use tools like PageSpeed Insights to check your theme’s performance. These types of tools provide information on how quickly your theme loads and offers suggestions for improvement.
When shipping media or other assets with your theme, be sure that they are optimized. This includes but is not limited to:
Images/Media: Ensure media items bundled with your theme are correctly sized, in the most appropriate format, and compressed to reduce load times.
CSS and JavaScript files: Make sure to include minified assets that will be loaded by the browser.

Theme Testing
The Theme Unit Test data is a WordPress import file will fill a WordPress site with enough stub data (posts, media, users) to test a theme.
The Theme Unit Tests are manual tests to walk through to test theme functionality and how the theme responds to the edge-cases of content and settings.
Theme Unit Test Overview
Fix PHP and WordPress errors. Add the following debug setting to your 
wp-config.php file to see deprecated function calls and other WordPress-related errors: 
define('WP_DEBUG', true);
See Deprecated Functions Hook for more information.
Check template files against Template File Checklist (see above).
Do a run-through using the Theme Unit Test.
Validate HTML and CSS. See Validating a Website.
Check for JavaScript errors.
Test in all your target browsers. For example Safari, Chrome, Opera, Firefox and Microsoft Edge.
Clean up any extraneous comments, debug settings or TODO items.
See Theme Review if you are publicly releasing the Theme by submitting it to the Themes Directory.

UI Best Practices
Logo Homepage Link
The logo at the top each page should send the user to the homepage of your site.
If you are using the recommended function, the_custom_logo() or the site logo block, the logo is linked to the homepage by default.
You can also add your logo manually. Assuming your logo is in your theme directory, this is how to display it in the 
header.php template file.
<a href="<?php echo esc_url( home_url( '/' ) ); ?>"><img src="<?php echo get_stylesheet_directory_uri(); ?>/logo.png" alt="<?php esc_attr_e( 'Home Page', 'textdmomain' );?>" /></a>
Descriptive Anchor Text
The anchor text is the visible text for a hyperlink. Good link text should give the reader an idea of the action that will take place when clicking it.
A bad example:
The best way to learn WordPress is to start using it. To Download WordPress, click here.
A better example:
Download WordPress and start using it. That's the best way to learn.
Style Links with Underlines
By default, browsers underline links to let the user know what is clickable. Some designers use CSS to turn off underlines for hyperlinks. This causes usability and accessibility problems, as it makes it more difficult to identify hyperlinks from the surrounding text.
Different Link Colors
Color is another visual cue that text is clickable. Styling hyperlinks with a different color than the surrounding text makes them easier to distinguish.
Hyperlinks are one of the few HTML features that have state. The two most important states are visited and unvisited.
Having different colors for these two states helps users identify the pages they’ve visited before. A good trick for taking the guess work out of visited links is to color them 10%-20% darker than the unvisited links.
There are 3 other states that links can have:
hover, when a mouse is over an element
focus, similar to hover but for keyboard users
active, when a user is clicking on a link
Since hover and focus have similar meanings, it is useful to give them the same styles.
Though hover and focus have similar meanings, they have different interaction patterns. If you choose a subtle hover state, you should have a more easily identifiable focus state. Hovering over a link is a directed activity, where the user knows where they are in the page and only needs to identify whether that spot is linked. Focus is an undirected activity, where the user needs to discover where their focus has moved to after shifting focus from the previous location.
Color Contrast
Color contrast refers to the difference between two colors. Contrast is low between navy blue and black. Contrast is high between white and black. WebAIM, a non-profit web accessibility organization, provides a color contrast calculator to help you determine the contrast in your website design. The WCAG 2.0 requires a ratio of 4.5:1 on normal text to be AA compliant.
Sufficient Font Size
Make your text easy to read. By making your text large enough, you increase the usability of your site and make the content easier to understand. 14px is the smallest text should be.
Associate Labels with Inputs
Labels inform the user what an input field is for. You can connect the label to the input by using the 
for attribute in the label. This will allow the user to click the label and focus on the input field.
<label for="username">Username</label>
<input type="text" id="username" name="login" />
Labels work for radio buttons as well. Since it works using the id field and not the name, each input for the group gets its own label.
<input type="radio" id="user_group_blogger" name="user_group" value="blogger" />
<label for="user_group_blogger">Blogger</label>
 
<input type="radio"  id="user_group_designer" name="user_group" value="designer" />
<label for="user_group_designer">Designer</label>
 
<input type="radio"  id="user_group_developer" name="user_group" value="developer" />
<label for="user_group_developer">Developer</label>
Placeholder Text in Forms
Placeholder text shows the user an example of what to type. When a user puts their cursor in the field, the placeholder text will disappear, while the label remains.
<label for="name">Name</label>
<input type="text" id="name" name="name" placeholder="John Smith" />
Use placeholders to suggest the type of data a field requires, and not as a substitute for the field label.
Descriptive Buttons
The web is filled with buttons that have unclear meanings. Remember the last time you used ‘OK’ or ‘submit’ on your login form? Choosing better words to display on your buttons can make your website easier to use. Try the pattern [verb] [noun] — Create user, Delete File, Update Password, Send Message. Each describes what will happen when the user clicks the button.

Theme Basics
In this chapter, you’ll begin learning how to build a theme. The anatomy of a theme and its parts will be broken down and explained.
You’ll begin by understanding the concepts of building a theme by looking at theme files and post types. Then you’ll learn how to keep your files organized within your theme.
You’ll also look at The Loop, which is responsible for pulling content out of the WordPress database.
Finally, you’ll learn more about adding features to your theme by using theme functions, including CSS & JavaScript, leveraging conditional tags to only show content you need, and working with default taxonomies and creating your own.

Theme Options – The Customize API
The Customize API (Customizer) is a framework for live-previewing any change to WordPress. It provides a unified interface for users to customize various aspects of their theme and their site, from colors and layouts to widgets, menus, and more. Themes and plugins alike can add options to the Customizer. The Customizer is the canonical way to add options to your theme.
The customizer as it appears in WordPress 4.6 with the Twenty Fifteen theme.
Customizer options can be granted to users with different capabilities on a granular basis, so while most options are visible only to administrators by default, other users may access certain options if you want them to be able to. Different parts of the Customizer can also be contextual to whether they’re relevant to the front-end context that the user is previewing. For example, the core widgets functionality only shows widget areas that are displayed on the current page; other widget areas are shown when the user navigates to a page that includes them within the Customizer preview window.
This section contains an overview of the Customize API, including code examples and discussion of best practices. For more details, it is strongly recommended that developers study the core customizer code (all core files containing “customize”). This is considered the canonical, official documentation for the Customize API outside of the inline documentation within the core code.

Theme Functionality
Now that you’re familiar with the basics of theme development, it’s time to start digging deeper into the world of themes. This section covers all of the basic theme functionality that you’ll need to consider while creating your theme:
Custom headers – learn how to give your users the flexibility of adding their own header image
Sidebars – add widgetized areas to your theme where users can add widgets
Widgets – create re-usable PHP objects that can be added to a sidebar
Navigation menus – register and display menus within your theme
Taxonomy Templates – create templates for your taxonomy archive pages
Pagination – work with WordPress’ built-in pagination
Comments – customize the comments template
Media – work with WordPress core’s media capabilities
Featured Images & Post Thumbnails – work with and customize post thumbnails
Post Formats – create different formats for displaying users’ posts
Internationalization – learn how to prepare your theme for translation into different languages
Localization – learn how to translate a WordPress theme
Accessibility – learn about accessibility best practices to ensure everyone can use your theme
Administration Menus – add menu items to the WordPress administration
404 Pages – create a custom 404 page
If you’re new to themes it’s worth working your way through each section, but you can also jump into a section if you’re looking for something specific.

References
This section contains lists of Template Tags and Conditional Tags.
Template Tags are used in your Template Files to display information dynamically or otherwise customize your site.
Conditional Tags are a boolean data type that can be used in your Template Files to alter the display of content depending on the conditions that the current page matches.

Template Files
We introduced template files earlier in the handbook.  This next section is going to break up the different template files through the post types that they display and provide a more in depth explanation of the purpose for these template files.  You’ll also get a handle on some practical use cases for the different template files.
You’ll start with post template files that deal with displaying the Post post type.  Then you’ll look at page template files that display the Page post type and drill down into specific page templates that WordPress has built in to its functionality.  Next you’ll learn about attachment template files which display the attachment post type.  You’ll also learn about how to display custom post types that are built by a plugin in the custom post type templates.  Lastly, you’ll touch on some partial and miscellaneous template files which are important to include but don’t necessarily display post types.
It’s important to understand WordPress doesn’t really break down template files down into specific types of template files such as post template files or attachment template files. Especially since many template files, such as 
index.php or 
search.php can display many different post types. To help you reference specific template files this handbook is categorizing them based on the post types they can display.

Your First Theme
Block Theme
This section is for a block theme.
Required Files
The only files needed for a block theme is,
index.html, which is the main template to display your list of posts. Index.html needs to be placed inside a folder called templates.
style.css file to style content.
theme.json file to set style properties in a structured way.
For advanced block theme development, you can add templates and template parts. For example,
You can create a templates directory inside the theme folder and put your templates there. Templates examples,
index.html
archive.html
single.html
page.html
You can create a parts directory inside the theme folder and put template parts. Template parts examples,
header.html
footer.html
sidebar.html
As you know the required files for block themes, now let’s create your first block theme.
Step 1 – Create a theme folder
First, create a new folder on your computer, and name it my-first-theme. This is where all of your theme’s files will go.
Step 2 – Create a style.css file
You can use any basic text editor on your computer to create a new file called style.css.
If you’re on a Windows-based machine use Notepad for now and if you’re using a Mac then use TextEdit.
Copy and paste the following code into your newly created style.css file:
/*
Theme Name: My First WordPress Theme
*/
Step 3 – Create a theme.json file
Create the theme.json file in the root folder, and copy and paste the following code:
{
“version”: 2,
“settings”: {
“layout”: {
“contentSize”: “840px”,
“wideSize”: “1100px”
}
}
}
Step 4 – Add index.html inside the templates folder
Inside your theme directory, create a templates folder. Inside the templates folder creates an index.html file.
Now, your theme structure should look like this,
templates/
index.html
style.css
theme.json
Your block theme is now ready. You can install and activate the theme. First, make the ZIP file of your theme directory. The ZIP file will be like, my-first-theme.zip
Step 5 – Install and activate your theme
Now, go to your WordPress admin panel and Appearance > Themes > Add New > Upload. Upload the my-first-theme.zip and click on install and then activate.
Congratulations – you’ve made your first WordPress block theme.
To know more about block themes, you can download the default Twenty Twenty-Three theme and use it as a reference.
Classic Theme
Required Files
As mentioned earlier in the “What is a Theme” section, the only files needed for a WordPress theme to work out of the box are an 
index.php file to display your list of posts and a 
style.css file to style the content.
Once you get into more advanced development territory and your themes grow in size and complexity, you’ll find it easier to break your theme into many separate files (called template files) instead. For example, most WordPress themes will also include:
header.php
index.php
sidebar.php
footer.php
We will cover creating separate files later in this handbook, but for now let’s get your first theme launched!
(Note: The following steps assume you have already completed the “Setting up a Development Environment” section.)
Step 1 – Create a theme folder
First, create a new folder on your computer, and name it my-first-theme. This is where all of your theme’s files will go.
Step 2 – Create a style.css file
You can use any basic text editor on your computer to create a new file called style.css.
If you’re on a Windows-based machine use Notepad for now and if you’re using a Mac then use TextEdit.
Copy and paste the following code into your newly created 
style.css file:
/*
Theme Name: My First WordPress Theme
*/
body {
background: #21759b;
}
Reference Gist
Step 3 – Create an index.php file
Now create a file named 
index.php and put it into your theme’s folder, adding the following code to it:
<!DOCTYPE html>
<html>
<head>
<meta charset="<?php bloginfo( 'charset' ); ?>">
<title><?php wp_title( '|', true, 'right' ); ?></title>
<link rel="stylesheet" href="<?php echo esc_url( get_stylesheet_uri() ); ?>" type="text/css" />
<?php wp_head(); ?>
</head>
<body>
<h1><?php bloginfo( 'name' ); ?></h1>
<h2><?php bloginfo( 'description' ); ?></h2>
<?php if ( have_posts() ) : while ( have_posts() ) : the_post(); ?>
<h3><?php the_title(); ?></h3>
<?php the_content(); ?>
<?php wp_link_pages(); ?>
<?php edit_post_link(); ?>
<?php endwhile; ?>
<?php
if ( get_next_posts_link() ) {
next_posts_link();
}
?>
<?php
if ( get_previous_posts_link() ) {
previous_posts_link();
}
?>
<?php else: ?>
<p>No posts found. :(</p>
<?php endif; ?>
<?php wp_footer(); ?>
</body>
</html>
Reference Gist
Step 4 – Install Your Theme
Copy your new theme into the 
wp-content/themes folder on your development environment and activate it for review and testing.
Step 5 – Activate Your Theme
Now that you’ve installed your theme, go to Admin > Appearance > Themes to activate it.
Using Your First Theme
Congratulations – you’ve just made your first WordPress theme!
If you activate your new theme and view it within a browser, you should see something like this:
Here’s how Your First Theme looks on the front end.
Okay, so it’s not the prettiest theme yet, but it’s a terrific start!
What have we learned?
Although your first theme may be missing the functionality and design elements that are found in other themes, the basic building blocks of a WordPress theme, as we have just created above, are all the same.
Remember that the key here is not to get caught up in how all those other things are done now, but to understand the guiding principles behind making WordPress themes that will stand the test of time, no matter how the code changes or the template file structure changes over time.
All websites, regardless of how they are created underneath the hood, need common elements: headers, primary content areas, menus, sidebars, footers, and the like. You’ll find that making WordPress themes is really just another way of crafting a website.
From this most basic theme, you’ll start learning about the building blocks that you put together to create a more complex theme.
Up Next
In Chapter 2: Theme Basics, we’ll dive further into themes and discuss the templates and other files that make up most themes, along with the PHP used to make dynamic themes, including:
Template Tags
The Loop
Theme Functions
Conditional Tags
and more

Categories, Tags, & Custom Taxonomies
Categories, tags, and taxonomies are all related and can be easily confused.
We’ll use the example of building a theme for a recipe website to help break down categories, tags, and taxonomies.
In our recipe website, the categories would be Breakfast, Lunch, Dinner, Appetizers, Soups, Salads, Sides, and Desserts. All recipes will fit within those categories, but users might want to search for something specific like chocolate desserts or ginger chicken dinners.
Chocolate, ginger, and chicken are all examples of tags.  They are another level of specificity that provides meaning to the user.
Lastly, there are taxonomies. In reality, categories and tags are examples of default taxonomies which simply are a way to organize content.  Taxonomies are the method of classifying content and data in WordPress. When you use a taxonomy you’re grouping similar things together. The taxonomy refers to the sum of those groups. As with Post Types, there are a number of default taxonomies, and you can also create your own.
Recipes are normally organized by category and tag, but there are some other helpful ways to break the recipes down to be more user friendly.  For example, the recipe website might want an easy way to display recipes by cook time. A custom taxonomy of cook time with 0-30 min, 30-min to an hour, 1 to 2 hours, 2+ hours would be a great breakdown.  Additionally, cook method such as grill, oven, stove, refrigerator, etc would be another example of a custom taxonomy that would be relevant for the site.  There could also be a custom taxonomy for how spicy the recipe is and then a rating from 1-5 on spiciness.
Default Taxonomies
The default taxonomies in WordPress are:
categories: a hierarchical taxonomy that organizes content in the post Post Type
tags: a non-hierarchical taxonomy that organizes content in the post Post Type
post formats: a method for creating formats for your posts. You can learn more about these on the Post Formats page.
Terms
Terms are items within your taxonomy. So, for example, if you have the Animaltaxonomy you would have the terms, dogs, cats, and sheep. Terms can be created via the WordPress admin, or you can use the wp_insert_term() function.
Database Schema
Taxonomies and terms are stored in the following database tables:
wp_terms – stores all of the terms
wp_term_taxonomy – places the term in a taxonomy
wp_term_relationships – relates the taxonomy to an object (for example, category to post)
Templates
WordPress offers several different hierarchies of templates for categories, tags, or custom taxonomies. More details on their structure and usage may be found on the Taxonomy Templates page.
Custom Taxonomies
It is possible to create new taxonomies in WordPress. You may, for example, want to create an author taxonomy on a book review website, or an actor taxonomy on a film site. As with custom post type it is recommended that you put this functionality in a plugin. This ensures that when the user changes their website’s design, their content is preserved in the plugin.
You can read more about creating custom taxonomies in the Plugin Developer Handbook.

Conditional Tags
Conditional Tags can be used in your Template Files in classic themes to alter the display of content depending on the conditions that the current page matches. They tell WordPress what code to display under specific conditions. Conditional Tags usually work with PHP if /else Conditional Statements.
The code begins by checking to see if a statement is true or false. If the statement is found to be true, the first set of code is executed. If it’s false, the first set of code is skipped, and the second set of code (after the else) is executed instead.
For example, you could ask if a user is logged in, and then provide a different greeting depending on the result.
if ( is_user_logged_in() ) :
	echo 'Welcome, registered user!';
else :
	echo 'Welcome, visitor!';
endif;
Note the close relation these tags have to WordPress Template Hierarchy.
Where to Use Conditional Tags
For a Conditional Tag to modify your data, the information must already have been retrieved from your database, i.e. the query must have already run. If you use a Conditional Tag before there is data, there’ll be nothing to ask the if/else statement about.
It’s important to note that WordPress loads 
functions.php before the query is run, so if you simply include a Conditional Tag in that file, it won’t work.
Two ways to implement Conditional Tags:
place it in a Template File
create a function out of it in 
functions.php that hooks into an action/filter that triggers at a later point
The Conditions For
Listed below are the conditions under which each of the following conditional statements proves to be true. Tags which can accept parameters are noted.
The Main Page
is_home()
This condition returns true when the main blog page is being displayed, usually in standard reverse chronological order. If your home page has been set to a Static Page instead, then this will only prove true on the page which you set as the “Posts page” in Settings > Reading.
The Front Page
is_front_page()
This condition returns true when the front page of the site is displayed, regardless of whether it is set to show posts or a static page.
Returns true when:
the main blog page is being displayed and
the Settings > Reading -> Front page displays option is set to Your latest posts
OR
when Settings > Reading -> Front page displays is set to A static page and
the Front Page value is the current Page being displayed.
The Administration Panels
is_admin()
This condition returns true when the Dashboard or the administration panels are being displayed.
A Single Post Page
is_single()
Returns true when any single Post (or attachment, or custom Post Type) is being displayed. This condition returns false if you are on a page.
is_single( '17' );
is_single() can also check for certain posts by ID and other parameters. The above example proves true when Post 17 is being displayed as a single Post.
is_single( 'Irish Stew' );
Parameters include Post titles, as well. In this case, it proves true when the Post with title “Irish Stew” is being displayed as a single Post.
is_single( 'beef-stew' );
Proves true when the Post with Post Slug “beef-stew” is being displayed as a single Post.
is_single( array( 17, 'beef-stew', 'Irish Stew' ) );
Returns true when the single post being displayed is either post ID 17, or the post_name is “beef-stew”, or the post_title is “Irish Stew”.
is_single( array( 17, 19, 1, 11 ) );
Returns true when the single post being displayed is either post ID = 17, post ID = 19, post ID = 1 or post ID = 11.
is_single( array( 'beef-stew', 'pea-soup', 'chilli' ) );
Returns true when the single post being displayed is either the post_name “beef-stew”, post_name “pea-soup” or post_name “chilli”.
is_single( array( 'Beef Stew', 'Pea Soup', 'Chilli' ) );
Returns true when the single post being displayed is either the post_title is “Beef Stew”, post_title is “Pea Soup” or post_title is “Chilli”.
Note: This function does not distinguish between the post ID, post title, or post name. A post named “17” would be displayed if a post ID of 17 was requested. Presumably the same holds for a post with the slug “17”.
A Single Post, Page, or Attachment
is_singular()
Returns true for any is_single, is_page, and is_attachment. It does allow testing for post types.
A Sticky Post
is_sticky()
Returns true if the “Stick this post to the front page” check box has been checked for the current post. In this example, no post ID argument is given, so the post ID for the Loop post is used.
is_sticky( '17' );
Returns true when Post 17 is considered a sticky post.
A Post Type
get_post_type()
You can test to see if the current post is of a certain type by including get_post_type() in your conditional. It’s not really a conditional tag, but it returns the registered post type of the current post.
if ( 'book' == get_post_type() ) { ... }
post_type_exists()
Returns true if a given post type is a registered post type. This does not test if a post is a certain post_type. Note: This function replaces a function called is_post_type which existed briefly in 3.0 development.
A Post Type is Hierarchical
is_post_type_hierarchical( $post_type )
Returns true if this $post_type has been set with hierarchical support when registered.
 is_post_type_hierarchical( 'book' );
Returns true if the book post type was registered as having support for hierarchical.
A Post Type Archive
is_post_type_archive()
Returns true on any post type archive.
is_post_type_archive( $post_type );
Returns true if on a post type archive page that matches $post_type (can be a single post type or an array of post types).
To turn on post type archives, use ‘has_archive’ => true, when registering the post type.
Any Page Containing Posts
comments_open()
When comments are allowed for the current Post being processed in the WordPress Loop.
pings_open()
When pings are allowed for the current Post being processed in the WordPress Loop.
A “PAGE” Page
This section refers to WordPress Pages, not any generic webpage from your blog, or in other words to the built in post_type ‘page’.
is_page()
When any Page is being displayed.
is_page( '42' );
When Page 42 (ID) is being displayed.
is_page( 'About Me And Joe' );
When the Page with a post_title of “About Me And Joe” is being displayed.
is_page( 'about-me' );
When the Page with a post_name (slug) of “about-me” is being displayed.
is_page( array( 42, 'about-me', 'About Me And Joe' ) );
Returns true when the Pages displayed is either post ID = 42, or post_name is “about-me”, or post_title is “About Me And Joe”.
is_page( array( 42, 54, 6 ) );
Returns true when the Pages displayed is either post ID = 42, or post ID = 54, or post ID = 6.
Testing for Paginated Pages
You can use this code to check whether you’re on the nth page in a Post or Page that has been divided into pages using the 
<!--nextpage--> QuickTag. This can be useful, for example, if you wish to display meta-data only on the first page of a post divided into several pages.
Example 1
<?php
$paged = $wp_query->get( 'page' );
if ( ! $paged || $paged < 2 ) :
	// This is not a paginated page (or it's simply the first page of a paginated page/post)
else :
	// This is a paginated page.
endif;
Example 2
<?php
$paged = get_query_var( 'page' ) ? get_query_var( 'page' ) : false;
if ( $paged == false ) :
	// This is not a paginated page (or it's simply the first page of a paginated page/post)
else :
	// This is a paginated page.
endif;
Testing for Sub-Pages
There is no 
is_subpage() function, but you can test this with a little code:
<?php
global $post; // if outside the loop
if ( is_page() && $post->post_parent ) :
	// This is a subpage
else :
	// This is not a subpage
endif;
Snippet 1
You can create your own is_subpage() function using the code in Snippet 2. Add it to your functions.php file. It tests for a parent page in the same way as Snippet 1, but will return the ID of the page parent if there is one, or false if there isn’t.
Snippet 2
<?php
function is_subpage() {
	// Load details about this page.
	global $post;
	// Test to see if the page has a parent
	if ( is_page() && $post->post_parent ) {
		// return the ID of the parent post
		return $post->post_parent;
	// there is no parent so ...
	} else {
		// ... the answer to the question is false
		return false;
	}
}
It is advisable to use a function like that in Snippet 2, rather than using the simple test like Snippet 1, if you plan to test for sub-pages frequently.
To test if the parent of a page is a specific page, for instance “About” (page id pid 2 by default), we can use the tests in Snippet 3. These tests check to see if we are looking at the page in question, as well as if we are looking at any child pages. This is useful for setting variables specific to different sections of a web site, so a different banner image, or a different heading.
Snippet 3
<?php
// The page is "About", or the parent of the page is "About".
if ( is_page( 'about' ) || '2' == $post->post_parent ) {
	$bannerimg = 'about.jpg';
} elseif ( is_page( 'learning' ) || '56' == $post->post_parent ) {
	$bannerimg = 'teaching.jpg';
} elseif ( is_page( 'admissions' ) || '15' == $post->post_parent ) {
	$bannerimg = 'admissions.jpg';
// Just in case we are at an unclassified page, perhaps the home page
} else {
	$bannerimg = 'home.jpg';
}
Snippet 4 is a function that allows you to carry out the tests above more easily. This function will return true if we are looking at the page in question (so “About”) or one of its sub pages (so a page with a parent with ID “2”).
Snippet 4
Add Snippet 4 to your functions.php file, and call is_tree( ‘id’ ) to see if the current page is the page, or is a sub page of the page. In Snippet 3, is_tree( ‘2’ ) would replace “is_page( ‘about’ ) || ‘2’ == $post->post_parent” inside the first if tag.
Note that if you have more than one level of pages the parent page is the one directly above and not the one at the very top of the hierarchy.
Is a Page Template
Allows you to determine whether or not you are in a page template or if a specific page template is being used.
is_page_template()
Is a Page Template being used?
is_page_template( 'about.php' );
Is Page Template ‘about’ being used? Note that unlike other conditionals, if you want to specify a particular Page Template, you need to use the filename, such as about.php or my_page_template.php.
Note: if the file is in a subdirectory you must include this as well. Meaning that this should be the filepath in relation to your theme as well as the filename, for example ‘page-templates/about.php’.
A Category Page
is_category()
When a Category archive page is being displayed.
is_category( '9' );
When the archive page for Category 9 is being displayed.
is_category( 'Stinky Cheeses' );
When the archive page for the Category with Name “Stinky Cheeses” is being displayed.
is_category( 'blue-cheese' );
When the archive page for the Category with Category Slug “blue-cheese” is being displayed.
is_category( array( 9, 'blue-cheese', 'Stinky Cheeses' ) );
Returns true when the category of posts being displayed is either term_ID 9, or slug “blue-cheese”, or name “Stinky Cheeses”.
in_category( '5' );
Returns true if the current post is in the specified category id.
in_category( array( 1, 2, 3 ) );
Returns true if the current post is in either category 1, 2, or 3.
! in_category( array( 4, 5, 6 ) );
Returns true if the current post is NOT in either category 4, 5, or 6. Note the ! at the beginning.
Note: Be sure to check your spelling when testing. There’s a big difference between “is” or “in”.
See also is_archive() and Category Templates.
A Tag Page
is_tag()
When any Tag archive page is being displayed.
is_tag( 'mild' );
When the archive page for tag with the slug of ‘mild’ is being displayed.
is_tag( array( 'sharp', 'mild', 'extreme' ) );
Returns true when the tag archive being displayed has a slug of either “sharp”, “mild”, or “extreme”.
has_tag();
When the current post has a tag. Must be used inside The Loop.
has_tag( 'mild' );
When the current post has the tag ‘mild’.
has_tag( array( 'sharp', 'mild', 'extreme' ) );
When the current post has any of the tags in the array.
See also is_archive() and Tag Templates.
A Taxonomy Page
is_tax()
When any Taxonomy archive page is being displayed.
is_tax( 'flavor' );
When a Taxonomy archive page for the flavor taxonomy is being displayed.
is_tax( 'flavor', 'mild');
When the archive page for the flavor taxonomy with the slug of ‘mild’ is being displayed.
is_tax( 'flavor', array( 'sharp', 'mild', 'extreme' ) );
Returns true when the flavor taxonomy archive being displayed has a slug of either “sharp”, “mild”, or “extreme”.
has_term()
Check if the current post has any of given terms. The first parameter should be an empty string. It expects a taxonomy slug/name as a second parameter.
has_term( 'green', 'color' );
When the current post has the term ‘green’ from taxonomy ‘color’.
has_term( array( 'green', 'orange', 'blue' ), 'color' );
When the current post has any of the terms in the array.
See also is_archive().
A Registered Taxonomy
taxonomy_exists()
When a particular taxonomy is registered via register_taxonomy(). Formerly is_taxonomy() , which was deprecated in Version 3.0
An Author Page
is_author()
When any Author page is being displayed.
is_author( '4' );
When the archive page for Author number (ID) 4 is being displayed.
is_author( 'Vivian' );
When the archive page for the Author with Nickname “Vivian” is being displayed.
is_author( 'john-jones' );
When the archive page for the Author with Nicename “john-jones” is being displayed.
is_author( array( 4, 'john-jones', 'Vivian' ) );
When the archive page for the author is either user ID 4, or user_nicename “john-jones”, or nickname “Vivian”.
See also is_archive() and Author Templates.
A Multi-author Site
is_multi_author()
When more than one author has published posts for a site. Available with Version 3.2.
A Date Page
is_date()
When any date-based archive page is being displayed (i.e. a monthly, yearly, daily or time-based archive).
is_year()
When a yearly archive is being displayed.
is_month()
When a monthly archive is being displayed.
is_day()
When a daily archive is being displayed.
is_time()
When an hourly, “minutely”, or “secondly” archive is being displayed.
is_new_day()
If today is a new day according to post date. Should be used inside the loop.
Any Archive Page
is_archive()
When any type of Archive page is being displayed. Category, Tag, Author and Date based pages are all types of Archives.
A Search Result Page
is_search()
When a search result page archive is being displayed.
A 404 Not Found Page
is_404()
When a page displays after an “HTTP 404: Not Found” error occurs.
A Privacy Policy Page
is_privacy_policy()
When the Privacy Policy page is being displayed.
An Attachment
is_attachment()
When an attachment document to a post or Page is being displayed. An attachment is an image or other file uploaded through the post editor’s upload utility. Attachments can be displayed on their own ‘page’ or template.
A Single Page, Single Post or Attachment
is_singular()
When any of the following return true: 
is_single(), 
is_page() or 
is_attachment().
is_singular( 'book' );
True when viewing a post of the Custom Post Types book.
is_singular( array( 'newspaper', 'book' ) );
True when viewing a post of the Custom Post Types newspaper or book.
A Syndication
is_feed()
When the site requested is a Syndication. This tag is not typically used by users; it is used internally by WordPress and is available for Plugin Developers.
A Trackback
is_trackback()
When the site requested is WordPress’ hook into its Trackback engine. This tag is not typically used by users; it is used internally by WordPress and is available for Plugin Developers.
A Preview
is_preview()
When a single post being displayed is viewed in Draft mode.
Has An Excerpt
has_excerpt()
When the current post has an excerpt
has_excerpt( 42 )
When the post 42 (ID) has an excerpt.
<?php
// Get $post if you're inside a function global $post;
if ( empty( $post->post_excerpt ) ) {
	// This post has no excerpt
} else {
	// This post has excerpt
}
Other use
When you need to hide the auto displayed excerpt and only display your post’s excerpts.
<?php
if ( ! has_excerpt() ) {
	echo '';
} else {
	the_excerpt();
}
Replace auto excerpt for a text or code.
<?php if ( ! has_excerpt() ) {
	// your text or code
}
Has A Nav Menu Assigned
has_nav_menu()
Whether a registered nav menu location has a menu assigned
Returns: assigned(true) or not(false)
Inside The Loop
in_the_loop()
Check to see if you are “inside the loop”. Useful for plugin authors, this conditional returns as true when you are inside the loop.
Is Sidebar Active
is_active_sidebar()
Check to see if a given sidebar is active (in use). Returns true if the sidebar (identified by name, id, or number) is in use, otherwise the function returns false.
Part of a Network (Multisite)
is_multisite()
Check to see whether the current site is in a WordPress MultiSite install.
Main Site (Multisite)
is_main_site()
Determines if a site is the main site in a network.
Admin of a Network (Multisite)
is_super_admin()
Determines if a user is a network (super) admin.
An Active Plugin
is_plugin_active()
Checks if a plugin is activated.
A Child Theme
is_child_theme()
Checks whether a child theme is in use.
Theme supports a feature
current_theme_supports()
Checks if various theme features exist.
Working Examples
Here are working samples to demonstrate how to use these conditional tags.
Single Post
This example shows how to use 
is_single() to display something specific only when viewing a single post page:
<?php
if ( is_single() ) {
	echo 'This is just one of many fabulous entries in the ' . single_cat_title() . ' category!';
}
Another example of how to use Conditional Tags in the Loop. Choose to display content or excerpt in index.php when this is a display single post or the home page.
<?php
if ( is_home() || is_single() ) {
	the_content();
} else {
	the_excerpt();
}
When you need display a code or element, in a place that is NOT the home page.
<?php if ( ! is_home() ) {
	// Insert your markup ...
}
Check for Multiple Conditionals
You can use PHP operators to evaluate multiple conditionals in a single if statement.
This is handy if you need to check whether combinations of conditionals evaluate to true or false.
<?php
// Check to see if any of 2 conditionals are met.
if ( is_single() || is_page() ) {
	// If it's a single post or a single page, do something special.
}
if ( is_archive() && ! is_category( 'nachos' ) ) {
	// If it's an archive page for any category EXCEPT nachos, do something special.
}
<?php
// Check to see if 3 conditionals are met.
if ( $query->is_main_query() && is_post_type_archive( 'products' ) && ! is_admin() ) {
	// If it's the main query on a custom post type archive for Products.
	// And if we're not in the WordPress admin, then do something special.
}
if ( is_post_type_archive( 'movies' ) || is_tax( 'genre' ) || is_tax( 'actor' ) ) {
	// If it's a custom post type archive for Movies.
	// Or it's a taxonomy archive for Genre.
	// Or it's a taxonomy archive for Actor, do something special.
}
Date Based Differences
If someone browses our site by date, let’s distinguish posts in different years by using different colors:
<?php if ( have_posts() ) : while ( have_posts() ) : the_post(); ?>
	<h2 id="post-<?php the_ID(); ?>">
		<a href="<?php the_permalink(); ?>" rel="bookmark"><?php the_title(); ?></a>
	</h2>
	<small>
		<?php the_time( 'F jS, Y' ); ?> by <?php the_author(); ?>
	</small>
	<?php
	// Are we showing a date-based archive?
	if ( is_date() ) {
		if ( date( 'Y' ) != get_the_date( 'Y' ) ) {
			// this post was written in a previous year
			// so let's style the content using the "oldentry" class
			echo '<div class="oldentry">';
		} else {
			echo '<div class="entry">';
		}
	} else {
		echo '<div class="entry">';
	}
	the_content( 'Read the rest of this entry »' );
	echo '</div>';
	?>
<?php endwhile; endif; ?>
Variable Sidebar Content
This example will display different content in your sidebar based on what page the reader is currently viewing.
<div id="sidebar">
<?php
// Let's generate info appropriate to the page being displayed.
if ( is_home() ) {
	// We're on the home page, so let's show a list of all top-level categories.
	wp_list_categories( 'optionall=0&sort_column=name&list=1&children=0' );
} elseif ( is_category() ) {
	// We're looking at a single category view, so let's show _all_ the categories.
	wp_list_categories( 'optionall=1&sort_column=name&list=1&children=1&hierarchical=1' );
} elseif ( is_single() ) {
	// We're looking at a single page, so let's not show anything in the sidebar.
} elseif ( is_page() ) {
	// We're looking at a static page. Which one?
	if ( is_page( 'About' ) ) {
		// Our about page.
		echo 'This is my about page!';
	} elseif ( is_page( 'Colophon' ) ) {
		echo 'This is my colophon page, running on WordPress ' . bloginfo( 'version' ) . '';
	} else {
		// Catch-all for other pages.
		echo 'Vote for Pedro!';
	}
} else {
	// Catch-all for everything else (archives, searches, 404s, etc)
	echo 'Pedro offers you his protection.';
}
?>
</div><!-- #sidebar -->
Helpful 404 Page
The Creating an Error 404 Page article as an example of using the PHP conditional function 
isset() in the Writing Friendly Messages section.
In the theme’s footer.php file
At times queries performed in other templates such as sidebar.php may corrupt certain conditional tags. For instance, in header.php a conditional tag works properly but doesn’t work in a theme’s footer.php. The trick is to put wp_reset_query before the conditional test in the footer. For example:
<?php
wp_reset_query();
if ( is_page( '2' ) ) {
	echo 'This is page 2!';
}
Conditional Tags Index
List of Conditional Tags
Function Reference
Reference

Including CSS & JavaScript (Archived)
This is an old page that has been archived in favor of the newer Including Assets documentation in the Core Concepts chapter. This page will eventually be removed and redirect to the newer doc.
When you’re creating your theme, you may want to create additional stylesheets or JavaScript files. However, remember that a WordPress website will not just have your theme active, it will also be using many different plugins. So that everything works harmoniously, it’s important that theme and plugins load scripts and stylesheets using the standard WordPress method. This will ensure the site remains efficient and that there are no incompatibility issues.
Adding scripts and styles to WordPress is a fairly simple process.   Essentially, you will create a function that will enqueue all of your scripts and styles. When enqueuing a script or stylesheet, WordPress creates a handle and path to find your file and any dependencies it may have (like jQuery) and then you will use a hook that will insert your scripts and stylesheets.
Enqueuing Scripts and Styles
The proper way to add scripts and styles to your theme is to enqueue them in the 
functions.php files. The 
style.css file is required in all themes, but it may be necessary to add other files to extend the functionality of your theme.
Tip: WordPress includes a number of JavaScript files as part of the software package, including commonly used libraries such as jQuery. Before adding your own JavaScript, check to see if you can make use of an included library.
The basics are:
Enqueue the script or style using 
wp_enqueue_script(), 
wp_enqueue_style(), or 
wp_enqueue_block_style.
Stylesheets
Your CSS stylesheets are used to customize the presentation of your theme. A stylesheet is also the file where information about your theme is stored. For this reason, the 
style.css file is required in every theme.
Rather then loading the stylesheet in your 
header.php file, you should load it in using 
wp_enqueue_style. In order to load your main stylesheet, you can enqueue it in 
functions.php
To enqueue 
style.css:
wp_enqueue_style( 'style', get_stylesheet_uri() );
This will look for a stylesheet named “style” and load it.
The basic function for enqueuing a style is:
wp_enqueue_style( $handle, $src, $deps, $ver, $media );
You can include these parameters:
$handle is simply the name of the stylesheet.
$src is where it is located. The rest of the parameters are optional.
$deps refers to whether or not this stylesheet is dependent on another stylesheet. If this is set, this stylesheet will not be loaded unless its dependent stylesheet is loaded first.
$ver sets the version number.
$media can specify which type of media to load this stylesheet in, such as ‘all’, ‘screen’, ‘print’ or ‘handheld.’
So if you wanted to load a stylesheet named “slider.css” in a folder named “CSS” in you theme’s root directory, you would use:
wp_enqueue_style( 'slider', get_template_directory_uri() . '/css/slider.css', false, '1.1', 'all');
Including CSS for block styles
In addition to 
wp_enqueue_style(), you can use 
wp_enqueue_block_style() to enqueue styles for blocks. wp_enqueue_block_style() requires WordPress version 5.9 or later.
A key part of creating block themes is performance. With, 
wp_enqueue_block_style(), the theme only loads the CSS for the selected block when the block is used on the page.
The additional style is loaded in the editor and the front, after the block style provided by WordPress and the Gutenberg plugin. You can use this method to add block styles that you can not add via 
theme.json. For example, media queries.
This code example changes the size and text color of the date in the latest comments block. Because this is a 
time HTML element that is nested inside other HTML elements, can not be styled using 
theme.json.
First, create a new CSS file with the name of the block: 
latest-comments.css.
Where you place the file depends on how you organize your theme files. In the example, the file is placed inside the folders 
assets/CSS/blocks.
The CSS class for the time element is 
wp-block-latest-comments__comment-date. The prefix and the block name are followed by the partial, separated by two underscores.
You can read more about the naming convention for the block editor in the coding guidelines.
The text color and font size are added with CSS custom properties that are generated from 
theme.json:
.wp-block-latest-comments__comment-date {
	color: var(--wp--preset--color--primary);
	font-size: var(--wp--preset--font-size--small);
}
Next, enqueue the block style inside the themes setup function.
The block name is placed inside an array to load more than one block style.
A 
foreach loop walks through each block in the array and creates a handle, src (source), and path argument.
wp_enqueue_block_style() then enqueues the file using the block name and argument:
wp_enqueue_block_style( "prefix/blockname", $args );
In the code example, the prefix is “core” since the style is for a core block. When you style blocks from plugins, you need to adjust the prefix.
function myfirsttheme_setup() {
	/*
	 * Load additional block styles.
	 */
	$styled_blocks = ['latest-comments'];
	foreach ( $styled_blocks as $block_name ) {
		$args = array(
			'handle' => "myfirsttheme-$block_name",
			'src'    => get_theme_file_uri( "assets/css/blocks/$block_name.css" ),
			$args['path'] = get_theme_file_path( "assets/css/blocks/$block_name.css" ),
		);
		wp_enqueue_block_style( "core/$block_name", $args );
	}
}
add_action( 'after_setup_theme', 'myfirsttheme_setup' );
Scripts
Any additional JavaScript files required by a theme should be loaded using 
wp_enqueue_script. This ensures proper loading and caching, and allows the use conditional tags to target specific pages. These are optional.
wp_enqueue_script uses a similar syntax to 
wp_enqueue_style.
Enqueue your script:
wp_enqueue_script( $handle, $src, $deps, $ver, $args );
$handle is the name for the script.
$src defines where the script is located.
$deps is an array that can handle any script that your new script depends on, such as jQuery.
$ver lets you list a version number.
$args an array of arguments that define footer printing (via an 
in_footer key) and script loading strategies (via a 
strategy key) such as 
defer or 
async. This replaces/overloads the 
$in_footer parameter as of WordPress version 6.3.
Your enqueue function may look like this:
wp_enqueue_script( 'script', get_template_directory_uri() . '/js/script.js', array( 'jquery' ), 1.1, true);
Delayed Script Loading
WordPress provides support for specifying a script loading strategy via the 
wp_register_script() and 
wp_enqueue_script() functions, by way of the 
strategy key within the new 
$args array parameter introduced in WordPress 6.3.
Supported strategies are as follows:
defer
Added by specifying an array key value pair of 
'strategy' => 'defer' to the $args parameter.
Scripts marked for deferred execution — via the 
defer script attribute — are only executed once the DOM tree has fully loaded (but before the 
DOMContentLoaded and window load events). Deferred scripts are executed in the same order they were printed/added in the DOM, unlike asynchronous scripts.
async
Added by specifying an array key value pair of 
'strategy' => 'async' to the 
$args parameter.
Scripts marked for asynchronous execution — via the 
async script attribute — are executed as soon as they are loaded by the browser. Asynchronous scripts do not have a guaranteed execution order, as script B (although added to the DOM after script A) may execute first given that it may complete loading prior to script A. Such scripts may execute either before the DOM has been fully constructed or after the 
DOMContentLoaded event.
Following is an example of specifying a loading strategy during script registration:
wp_register_script( 
    'foo', 
    '/path/to/foo.js', 
    array(), 
    '1.0.0', 
    array( 
        'strategy'  => 'defer',
    )
);
The same approach applies when using 
wp_enqueue_script().
When specifying a delayed script loading strategy, consideration of the script’s dependency tree (its dependencies and/or dependents) is taken into account when deciding on an “eligible strategy” so as not to result in application of a strategy that is valid for one script but detrimental to others in the tree by causing an unintended out of order of execution. As a result of such logic, the intended loading strategy that you pass via the 
$args parameter may not be the final (chosen) strategy, but it will never be detrimental to (or stricter than) the intended strategy.
The Comment Reply Script
WordPress comments have quite a bit of functionality in them right out of the box, including threaded comments and enhanced comment forms. In order for comments to work properly, they require some JavaScript. However, since there are certain options that need to be defined within this JavaScript, the comment-reply script should be added to every classic theme that uses comments.
In block themes, the script is included when you place a comment block. You do not need to add it manually.
The proper way to include comment reply in classic themes is to use conditional tags to check if certain conditions exist, so that the script isn’t being loaded unnecessarily. For instance, you can only load scripts on single post pages using 
is_singular, and check to make sure that “Enable threaded comments” is selected by the user. So you can set up a function like:
if ( is_singular() && comments_open() && get_option( 'thread_comments' ) ) {
	wp_enqueue_script( 'comment-reply' );
}
If comments are enabled by the user, and we are on a post page, then the comment reply script will be loaded. Otherwise, it will not.
Combining Enqueue Functions
It is best to combine all enqueued scripts and styles into a single function, and then call them using the 
wp_enqueue_scripts action. This function and action should be located somewhere below the initial setup (performed above):
function add_theme_scripts() {
	wp_enqueue_style( 'style', get_stylesheet_uri() );
	wp_enqueue_style( 'slider', get_template_directory_uri() . '/css/slider.css', array(), '1.1', 'all' );
	wp_enqueue_script( 'script', get_template_directory_uri() . '/js/script.js', array( 'jquery' ), 1.1, true );
	if ( is_singular() && comments_open() && get_option( 'thread_comments' ) ) {
		wp_enqueue_script( 'comment-reply' );
	}
}
add_action( 'wp_enqueue_scripts', 'add_theme_scripts' );
Default Scripts Included and Registered by WordPress
By default, WordPress includes many popular scripts commonly used by web developers, as well as the scripts used by WordPress itself. Some of them are listed on this reference page:
wp_enqueue_script()
The list is far from complete. You can find a full list of included files in wp-includes/script-loader.php.
/
Changelog:
Updated 2023-02-24: Added information about wp_enqueue_block_style() .
Updated 2024-06-06: Added alert to point readers to new doc.

Linking Theme Files & Directories
Linking to Core Theme Files
As you’ve learned, WordPress themes are built from a number of different template files. At the very least this will usually include a 
sidebar.php, 
header.php and 
footer.php. These are called using Template Tags, for example:
get_header() ;
get_footer() ;
get_sidebar() ;
You can create custom versions of these files can be called as well by naming the file 
sidebar-{your_custom_template}.php, 
header-{your_custom_template}.php and 
footer-{your_custom_template}.php. You can then use Template Tags with the custom template name as the only parameter, like this:
get_header( 'your_custom_template' );
get_footer( 'your_custom_template' );
get_sidebar( 'your_custom_template' );
WordPress creates pages by assembling various files. Aside from the standard files for the header, footer and sidebar, you can create custom template files and call them at any location in the page using get_template_part() . To create a custom template file in your theme give the file an appropriate name and use the same custom template system as with the header, sidebar and footer files:
slug-template.php
For example, if you would like to create a custom template to handle your post content you could create a template file called 
content.php and then add a specific content layout for product content by extending the file name to 
content-product.php. You would then load this template file in your theme like this:
get_template_part( 'content', 'product' );
If you want to add more organization to your templates, you can place them in their own directories within your theme directory. For example, suppose you add a couple more content templates for profiles and locations, and group them in their own directory called 
content-templates.
The theme hierarchy for your theme called 
my-theme might look like the following. 
style.css and 
page.php are included for context.
themes
my-theme
content-templates
content-location.php
content-product.php
content-profile.php
style.css
To include your content templates, prepend the directory names to the 
slug argument like this:
get_template_part( 'content-templates/content', 'location' );
get_template_part( 'content-templates/content', 'product' );
get_template_part( 'content-templates/content', 'profile' );
Linking to Theme Directories
To link to the theme’s directory, you can use the following function:
get_theme_file_uri() ;
If you are not using a child theme, this function will return the full URI to your theme’s main folder. You can use this to reference sub-folders and files in your theme like this:
echo get_theme_file_uri( 'images/logo.png' );
If you are using a child theme then this function will return the URI of the file in your child theme if it exists. If the file cannot be found in your child theme, the function will return the URI of the file in the parent theme. This is particularly important to keep in mind when distributing a theme or in any other case where a child theme may or may not be active.
To access the path to a file in your theme’s directories, you can use the following function:
get_theme_file_path() ;
Like get_theme_file_uri() , this will access the path of the file in the child theme if it exists. If the file cannot be found in the child theme, the function will access the path to the file in the parent theme.
In a child theme, you can link to a file URI or path in the parent theme’s directories using the following functions:
get_parent_theme_file_uri() ;
get_parent_theme_file_path() ;
As with  
get_theme_file_uri(), you can reference sub-folders and files like this:
echo get_parent_theme_file_uri( 'images/logo.png' );
//or
echo get_parent_theme_file_path( 'images/logo.png' );
Take care when referencing files that may not be present, as these functions will return the URI or file path whether the file exists or not. If the file is missing, these functions will return a broken link.
The functions get_theme_file_uri() , get_theme_file_path() , get_parent_theme_file_uri() , get_parent_theme_file_path() were introduced in WordPress 4.7.
For previous WordPress versions, use get_template_directory_uri() , get_template_directory() , get_stylesheet_directory_uri() , get_stylesheet_directory() .
Take note that the newer 4.7 functions run the older functions anyway as part of the checking process so it makes sense to use the newer functions when possible.
Dynamic Linking in Templates
Regardless of your permalink settings, you can link to a page or post dynamically by referring to its unique numerical ID (seen in several pages in the admin interface) with
<a href="<?php echo get_permalink($ID); ?>">This is a link</a>
This is a convenient way to create page menus as you can later change page slugs without breaking links, as IDs will stay the same. However, this might increase database queries.

Main Stylesheet (style.css)
The style.css is a stylesheet (CSS) file required for every WordPress theme. It controls the presentation (visual design and layout) of the website pages.
Location
In order for WordPress to recognize the set of theme template files as a valid theme, the style.css file needs to be located in the root directory of your theme, not a subdirectory.
For more detailed explanation on how to include the style.css file in a theme, see the “Stylesheets” section of Enqueuing Scripts and Styles.
Basic Structure
WordPress uses the header comment section of a style.css to display information about the theme in the Appearance (Themes) dashboard panel.
Example
Here is an example of the header part of style.css.
/*
Theme Name: Twenty Twenty
Theme URI: https://wordpress.org/themes/twentytwenty/
Author: the WordPress team
Author URI: https://wordpress.org/
Description: Our default theme for 2020 is designed to take full advantage of the flexibility of the block editor. Organizations and businesses have the ability to create dynamic landing pages with endless layouts using the group and column blocks. The centered content column and fine-tuned typography also makes it perfect for traditional blogs. Complete editor styles give you a good idea of what your content will look like, even before you publish. You can give your site a personal touch by changing the background colors and the accent color in the Customizer. The colors of all elements on your site are automatically calculated based on the colors you pick, ensuring a high, accessible color contrast for your visitors.
Tags: blog, one-column, custom-background, custom-colors, custom-logo, custom-menu, editor-style, featured-images, footer-widgets, full-width-template, rtl-language-support, sticky-post, theme-options, threaded-comments, translation-ready, block-styles, wide-blocks, accessibility-ready
Version: 1.3
Requires at least: 5.0
Tested up to: 5.4
Requires PHP: 7.0
License: GNU General Public License v2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html
Text Domain: twentytwenty
This theme, like WordPress, is licensed under the GPL.
Use it to make something cool, have fun, and share what you've learned with others.
*/
WordPress Theme Repository uses the number after “Version” in this file to determine if the theme has a new version available.
Explanations
Items indicated with (*) are required for a theme in the WordPress Theme Repository.
Theme Name (*): Name of the theme.
Theme URI: The URL of a public web page where users can find more information about the theme.
Author (*): The name of the individual or organization who developed the theme. Using the Theme Author’s wordpress.org username is recommended.
Author URI: The URL of the authoring individual or organization.
Description (*): A short description of the theme.
Version (*): The version of the theme, written in X.X or X.X.X format.
Requires at least (*): The oldest main WordPress version the theme will work with, 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, in X.X format.
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.
Tags: Words or phrases that allow users to find the theme using the tag filter. A full list of tags is in the Theme Review Handbook.
Domain Path: Used so that WordPress knows where to find the translation when the theme is disabled. Defaults to 
/languages.
After the required header section, style.css can contain anything a regular CSS file has.
Style.css for a Child Theme
If your theme is a Child Theme, the Template line is required in style.css header.
/*
Theme Name: My Child Theme
Template: twentytwenty
*/
For more information on creating a Child Theme, visit the Child Themes page.

Organizing Theme Files
While WordPress themes technically only require two files (
index.php in classic themes and 
index.html in block themes, and 
style.css), they usually are made up of many files. That means they can quickly become disorganized! This section will show you how to keep your files organized.
Theme folder and file structure
As mentioned previously, the default Twenty themes are some of the best examples of good theme development. For instance, here is how the Twenty Seventeen Theme organizes its file structure:
.
├── assets (dir)/
│   ├── css (dir)
│   ├── images (dir)
│   └── js (dir)
├── inc (dir)
├── template-parts (dir)/
│   ├── footer (dir)
│   ├── header (dir)
│   ├── navigation (dir)
│   ├── page (dir)
│   └── post (dir)
├── 404.php
├── archive.php
├── comments.php
├── footer.php
├── front-page.php
├── functions.php
├── header.php
├── index.php
├── page.php
├── README.txt
├── rtl.css
├── screenshot.png
├── search.php
├── searchform.php
├── sidebar.php
├── single.php
└── style.css
You can see that the main theme template files are in the root directory, while JavaScript, CSS, images are placed in assets directory, template-parts are placed in under respective subdirectory of template-parts and collection of  functions related to core functionalities are placed in inc directory.
There are no required folders in classic themes. In block themes, templates must be placed inside a folder called templates, and all template parts must be placed inside a folder called parts.
style.css should reside in the root directory of your theme not within the CSS directory.
Languages folder
It’s best practice to internationalize your theme so it can be translated into other languages. Default themes include the 
languages folder, which contains a .pot file for translation and any translated .mo files. While 
languages is the default name of this folder, you can change the name. If you do so, you must update 
load_theme_textdomain().

Post Types
There are many different types of content in WordPress. These content types are normally described as Post Types, which may be a little confusing since it refers to all different types of content in WordPress. For example, a post is a specific Post Type, and so is a page.
Internally, all of the Post Types are stored in the same place — in the wp_posts database table — but are differentiated by a database column called post_type.
In addition to the default Post Types, you can also create Custom Post Types.
The Template files page briefly mentioned that different Post Types are displayed by different Template files.  As the whole purpose of a Template file is to display content a certain way, the Post Types purpose is to categorize what type of content you are dealing with. Generally speaking, certain Post Types are tied to certain template files.
Default Post Types
There are several default Post Types readily available to users or internally used by the WordPress installation. The most common are:
Post (Post Type: ‘post’)
Page (Post Type: ‘page’)
Attachment (Post Type: ‘attachment’)
Revision (Post Type: ‘revision’)
Navigation menu (Post Type: ‘nav_menu_item’)
Block templates (Post Type: ‘wp_template’)
Template parts (Post Type: ‘wp_template_part’)
The Post Types above can be modified and removed by a plugin or theme, but it’s not recommended that you remove built-in functionality for a widely-distributed theme or plugin.
It’s out of the scope of this handbook to explain other post types in detail. However, it is important to note that you will interact with and build the functionality of navigation menus and that will be detailed later in this handbook.
Post
Posts are used in blogs. They are:
displayed in reverse sequential order by time, with the newest post first
have a date and time stamp
may have the default taxonomies of categories and tags applied
are used for creating feeds
The template files that display the Post post type are:
single and 
single-post
category and all its iterations
tag and all its iterations
taxonomy and all its iterations
archive and all its iterations
author and all its iterations
date and all its iterations
search
home
index
Read more about Post Template Files in classic themes.
Page
Pages are a static Post Type, outside of the normal blog stream/feed. Their features are:
non-time dependent and without a time stamp
are not organized using the categories and/or tags taxonomies
can be organized in a hierarchical structure — i.e. pages can be parents/children of other pages
The template files that display the Page post type are:
page and all its iterations
front-page
search
index
Read more about Page Template Files in classic themes.
Attachment
Attachments are commonly used to display images or media in content, and may also be used to link to relevant files. Their features are:
contain information (such as name or description) about files uploaded through the media upload system
for images, this includes metadata information stored in the wp_postmeta table (including size, thumbnails, location, etc)
The template files that display the Attachment post type are:
MIME_type
attachment
single-attachment
single
index
Read more about Attachment Template Files in classic themes.
Custom Post Types
Using Custom Post Types, you can create your own post type. It is not recommend that you place this functionality in your theme. This type of functionality should be placed/created in a plugin. This ensures the portability of your user’s content, and that if the theme is changed the content stored in the Custom Post Types won’t disappear.
You can learn more about creating custom post types in the WordPress Plugin Developer Handbook.
While you generally won’t develop Custom Post Types in your theme, you may want to code ways to display Custom Post Types that were created by a plugin.  The following templates can display Custom post types:
single-{post-type}
archive-{post-type}
search
index
Read more about Custom Post Type Templates in classic themes.

Reworking Theme Files & Organization
Theme folder and file structure
While WordPress themes technically only require two files (
index.php and 
style.css), they usually are made up of many files and can become quickly disorganized.
In the last section, Template Files, you set up your 
header.php, footer.php, page.php, home.php, and single.php files.
Let’s look at the Twenty Twelve theme default themes as one example of good file structure and organization.  While this may be a bit overwhelming at first, let’s break it down. Can you find the templates you just built?
While there are still a lot of files, their names help provide a context of what they are. Basically, each file handles a feature of WordPress.  I.e. 
comments.php deals with how the theme will handle comments; 
image.php instructs the theme how to handle images, etc.  Don’t worry about adding these files unless you need them.
You can see that the main theme template files are in the theme’s root directory, while JavaScript, languages, CSS, and page template files are placed within their own folders.
At this time, there are no required folders within a WordPress theme. However, WordPress does recognize the following folders by default:
Page templates folder
The custom page templates, named page-templates (since 3.4.0), allow for better organization of template files. Custom page template files placed in this folder are automatically recognized by WordPress.
Language folder
If you wish to internationalize your theme so it’s usable in other languages, you can create a languages folder to contain translations.

Template Files
Template files are used throughout WordPress themes, but first let’s learn about the terminology.
Template Terminology
The term “template” is used in different ways when working with WordPress themes:
Templates files exist within a theme and express how your site is displayed.
Template Hierarchy is the logic WordPress uses to decide which theme template file(s) to use, depending on the content being requested.
Page Templates are those that apply to pages, posts, and custom post types to change their look and feel.
In classic themes, Template Tags are built-in WordPress functions you can use inside a template file to retrieve and display data (such as 
the_title() and 
the_content()).
In block themes, blocks are used instead of template tags.
Template files
WordPress themes are made up of template files.
In classic themes these are PHP files that contain a mixture of HTML, Template Tags, and PHP code.
In block themes these are HTML files that contain HTML markup representing blocks.
When you are building your theme, you will use template files to affect the layout and design of different parts of your website. For example, you would use a 
header template or template part to create a header.
When someone visits a page on your website, WordPress loads a template based on the request. The type of content that is displayed by the template file is determined by the Post Type associated with the template file. The Template Hierarchy describes which template file WordPress will load based on the type of request and whether the template exists in the theme. The server then parses the code in the template and returns HTML to the visitor.
The most critical template file is 
the index, which is the catch-all template if a more-specific template can not be found in the template hierarchy. Although a theme only needs a 
index template, typically themes include numerous templates to display different content types and contexts.
Template partials
A template part is a piece of a template that is included as a part of another template, such as a site header. Template part can be embedded in multiple templates, simplifying theme creation. Common template parts include:
header.php or 
header.html for generating the site’s header
footer.php or 
footer.html for generating the footer
sidebar.php or 
sidebar.html for generating the sidebar
While the above template files are special-case in WordPress and apply to just one portion of a page, you can create any number of template partials and include them in other template files.
In block themes, template parts must be placed inside a folder called parts.
Common WordPress template files
Below is a list of some basic theme templates and files recognized by WordPress.
index.php (classic theme) or index.html (block theme)
The main template file. It is required in all themes.
style.css
The main stylesheet. It is required in all themes and contains the information header for your theme.
rtl.css
The right-to-left stylesheet is included automatically if the website language’s text direction is right-to-left.
front-page.php (classic theme) or front-page.html (block theme)
The front page template is always used as the site front page if it exists, regardless of what settings on Admin > Settings > Reading.
home.php (classic theme) or home.html (block theme)
The home page template is the front page by default. If you do not set WordPress to use a static front page, this template is used to show latest posts.
singular.php (classic theme) or singular.html (block theme)
The singular template is used for posts when 
single.php is not found, or for pages when 
page.php are not found. If 
singular.php is not found, 
index.php is used.
single.php (classic theme) or single.html (block theme)
The single post template is used when a visitor requests a single post.
single-{post-type}.php (classic theme) or single-{post-type}.html (block theme)
The single post template used when a visitor requests a single post from a custom post type. For example, 
single-book.php would be used for displaying single posts from a custom post type named book.
archive-{post-type}.php (classic theme) or archive-{post-type}.html (block theme)
The archive post type template is used when visitors request a custom post type archive. For example, 
archive-books.php would be used for displaying an archive of posts from the custom post type named books. The archive template file is used if the 
archive-{post-type} template is not present.
page.php (classic theme) or page.html (block theme)
The page template is used when visitors request individual pages, which are a built-in template.
page-{slug}.php (classic theme) or page-{slug}.html (block theme)
The page slug template is used when visitors request a specific page, for example one with the “about” slug (page-about.php).
category.php (classic theme) or category.html (block theme)
The category template is used when visitors request posts by category.
tag.php (classic theme) or tag.html (block theme)
The tag template is used when visitors request posts by tag.
taxonomy.php (classic theme) or taxonomy.html (block theme)
The taxonomy term template is used when a visitor requests a term in a custom taxonomy.
author.php (classic theme) or author.html (block theme)
The author page template is used whenever a visitor loads an author page.
date.php (classic theme) or date.html (block theme)
The date/time template is used when posts are requested by date or time. For example, the pages generated with these slugs:
http://example.com/blog/2014/
http://example.com/blog/2014/05/
http://example.com/blog/2014/05/26/
archive.php (classic theme) or archive.html (block theme)
The archive template is used when visitors request posts by category, author, or date. Note: this template will be overridden if more specific templates are present like 
category.php, 
author.php, and 
date.php.
search.php (classic theme) or search.html (block theme)
The search results template is used to display a visitor’s search results.
attachment.php (classic theme) or attachment.html (block theme)
The attachment template is used when viewing a single attachment like an image, pdf, or other media file.
image.php (classic theme) or image.html (block theme)
The image attachment template is a more specific version of 
attachment.php and is used when viewing a single image attachment. If not present, WordPress will use 
attachment.php instead.
404.php (classic theme) or 404.html (block theme)
The 404 template is used when WordPress cannot find a post, page, or other content that matches the visitor’s request.
comments.php
The comments template in classic themes. In block themes, blocks are used instead.
Using template files
Classic themes
In classic themes, within WordPress templates, you can use Template Tags to display information dynamically, include other template files, or otherwise customize your site.
For example, in your 
index.php you can include other files in your final generated page:
To include the header, use get_header()
To include the sidebar, use get_sidebar()
To include the footer, use get_footer()
To include the search form, use get_search_form()
To include custom theme files, use get_template_part()
Here is an example of WordPress template tags to include specific templates into your page:
<?php get_sidebar(); ?>
<?php get_template_part( 'featured-content' ); ?>
<?php get_footer(); ?>
There’s an entire page on Template Tags that you can dive into to learn all about them.
Refer to the section Linking Theme Files & Directories for more information on linking component templates.
Block themes
In block themes you use blocks instead of template tags. Block markup is the HTML code that WordPress uses to display the block. Template parts are blocks, and you add them to your template files the same way as you add blocks.
To include a header or footer template part, add the block markup for the template part. The 
slug is the name of the part. If the file you want to include is called 
header.html, then the slug is “header”:
<!-- wp:template-part {"slug":"header"} /-->
(your page content)
<!-- wp:template-part {"slug":"footer"} /-->
To include the search form, use the block markup for the search block:
<!-- wp:search {"label":"Search","buttonText":"Search"} /-->

Template Hierarchy
As discussed, template files are modular, reusable files, used to generate the web pages on your WordPress site. Some template files (such as the header and footer template) are used on all of your site’s pages, while others are used only under specific conditions.
This article explains how WordPress determines which template file(s) to use on individual pages. If you want to customize an existing WordPress theme it will help you decide which template file needs to be edited.
You can also use Conditional Tags to control which templates are loaded on a specific page.
The Template File Hierarchy
Overview
WordPress uses the query string to decide which template or set of templates should be used to display the page. The query string is information that is contained in the link to each part of your website.
Put simply, WordPress searches down through the template hierarchy until it finds a matching template file. To determine which template file to use, WordPress:
Matches every query string to a query type to decide which page is being requested (for example, a search page, a category page, etc);
Selects the template in the order determined by the template hierarchy;
Looks for template files with specific names in the current theme’s directory and uses the first matching template file as specified by the hierarchy.
With the exception of the basic 
index.php template file, you can choose whether you want to implement a particular template file or not.
In these examples, the PHP file extension is used. In block themes, HTML files are used instead, but the template hierarchy is the same.
If WordPress cannot find a template file with a matching name, it will skip to the next file in the hierarchy. If WordPress cannot find any matching template file, the theme’s 
index.php file will be used.
When you are using a child theme, any file you add to your child theme will over-ride the same file in the parent theme. For example, both themes contain the same template 
category.php, then child theme’s template is used.
If a child theme contains the specific template such as 
category-unicorns.php and the parent theme contains lower prioritized template such as 
category.php, then child theme’s 
category-unicorns.php is used.
Contrary, if a child theme contains general template only such as 
category.php and the parent theme contains the specific one such as 
category-unicorns.php, then parent’s template 
category-unicorns.php is used.
Examples
If your blog is at 
http://example.com/blog/ and a visitor clicks on a link to a category page such as 
http://example.com/blog/category/your-cat/, WordPress looks for a template file in the current theme’s directory that matches the category’s ID to generate the correct page. More specifically, WordPress follows this procedure:
Looks for a template file in the current theme’s directory that matches the category’s slug. If the category slug is “unicorns,” then WordPress looks for a template file named 
category-unicorns.php.
If 
category-unicorns.php is missing and the category’s ID is 4, WordPress looks for a template file named 
category-4.php.
If 
category-4.php is missing, WordPress will look for a generic category template file, 
category.php.
If 
category.php does not exist, WordPress will look for a generic archive template, 
archive.php.
If 
archive.php is also missing, WordPress will fall back to the main theme template file, 
index.php.
Visual Overview
The following diagram shows which template files are called to generate a WordPress page based on the WordPress template hierarchy.
The Template Hierarchy In Detail
While the template hierarchy is easier to understand as a diagram, the following sections describe the order in which template files are called by WordPress for a number of query types.
Home Page display
By default, WordPress sets your site’s home page to display your latest blog posts. This page is called the blog posts index. You can also set your blog posts to display on a separate static page. The template file 
home.php is used to render the blog posts index, whether it is being used as the front page or on separate static page. If 
home.php does not exist, WordPress will use 
index.php.
home.php
index.php
If 
front-page.php exists, it will override the 
home.php template.
Front Page display
The 
front-page.php template file is used to render your site’s front page, whether the front page displays the blog posts index (mentioned above) or a static page. The front page template takes precedence over the blog posts index (
home.php) template. If the 
front-page.php file does not exist, WordPress will either use the 
home.php or 
page.php files depending on the setup in Settings → Reading. If neither of those files exist, it will use the 
index.php file.
front-page.php – Used for both “your latest posts” or “a static page” as set in the front page displays section of Settings → Reading.
home.php – If WordPress cannot find 
front-page.php and “your latest posts” is set in the front page displays section, it will look for 
home.php. Additionally, WordPress will look for this file when the posts page is set in the front page displays section.
page.php – When “front page” is set in the front page displays section.
index.php – When “your latest posts” is set in the front page displays section but 
home.php does not exist or when front page is set but 
page.php does not exist.
As you can see, there are a lot of rules to what path WordPress takes. Using the chart above is the best way to determine what WordPress will display.
Privacy Policy Page display
The 
privacy-policy.php template file is used to render your site’s Privacy Policy page. The Privacy Policy page template takes precedence over the static page (
page.php) template. If the 
privacy-policy.php file does not exist, WordPress will either use the 
page.php or 
singular.php files depending on the available templates. If neither of those files exist, it will use the 
index.php file.
privacy-policy.php – Used for the Privacy Policy page set in the Change your Privacy Policy page section of Settings → Privacy.
custom template file – The page template assigned to the page. See 
get_page_templates().
page-{slug}.php – If the page slug is 
privacy, WordPress will look to use 
page-privacy.php.
page-{id}.php – If the page ID is 6, WordPress will look to use 
page-6.php.
page.php
singular.php
index.php
Single Post
The single post template file is used to render a single post. WordPress uses the following path:
single-{post-type}-{slug}.php – (Since 4.4) First, WordPress looks for a template for the specific post. For example, if post type is 
product and the post slug is 
dmc-12, WordPress would look for 
single-product-dmc-12.php.
single-{post-type}.php – If the post type is 
product, WordPress would look for 
single-product.php.
single.php – WordPress then falls back to 
single.php.
singular.php – Then it falls back to 
singular.php.
index.php – Finally, as mentioned above, WordPress ultimately falls back to 
index.php.
Single Page
The template file used to render a static page (
page post-type). Note that unlike other post-types, 
page is special to WordPress and uses the following path:
custom template file – The page template assigned to the page. See 
get_page_templates().
page-{slug}.php – If the page slug is 
recent-news, WordPress will look to use 
page-recent-news.php.
page-{id}.php – If the page ID is 6, WordPress will look to use 
page-6.php.
page.php
singular.php
index.php
Category
Rendering category archive index pages uses the following path in WordPress:
category-{slug}.php – If the category’s slug is 
news, WordPress will look for 
category-news.php.
category-{id}.php – If the category’s ID is 
6, WordPress will look for 
category-6.php.
category.php
archive.php
index.php
Tag
To display a tag archive index page, WordPress uses the following path:
tag-{slug}.php – If the tag’s slug is 
sometag, WordPress will look for 
tag-sometag.php.
tag-{id}.php – If the tag’s ID is 
6, WordPress will look for 
tag-6.php.
tag.php
archive.php
index.php
Custom Taxonomies
Custom taxonomies use a slightly different template file path:
taxonomy-{taxonomy}-{term}.php – If the taxonomy is 
sometax, and taxonomy’s term is 
someterm, WordPress will look for 
taxonomy-sometax-someterm.php. In the case of post formats, the taxonomy is ‘post_format’ and the terms are ‘post-format-{format}. i.e. 
taxonomy-post_format-post-format-link.php for the link post format.
taxonomy-{taxonomy}.php – If the taxonomy were 
sometax, WordPress would look for 
taxonomy-sometax.php.
taxonomy.php
archive.php
index.php
Custom Post Types
Custom Post Types use the following path to render the appropriate archive index page.
archive-{post_type}.php – If the post type is 
product, WordPress will look for 
archive-product.php.
archive.php
index.php
(For rendering a single post type template, refer to the single post display section above.)
Author display
Based on the above examples, rendering author archive index pages is fairly explanatory:
author-{nicename}.php – If the author’s nice name is 
matt, WordPress will look for 
author-matt.php.
author-{id}.php – If the author’s ID were 
6, WordPress will look for 
author-6.php.
author.php
archive.php
index.php
Date
Date-based archive index pages are rendered as you would expect:
date.php
archive.php
index.php
Search Result
Search results follow the same pattern as other template types:
search.php
index.php
404 (Not Found)
Likewise, 404 template files are called in this order:
404.php
index.php
Attachment
Rendering an attachment page (
attachment post-type) uses the following path:
{MIME-type}.php – can be any MIME type (For example: 
image.php, 
video.php, 
pdf.php). For 
text/plain, the following path is used (in order):
text-plain.php
plain.php
text.php
attachment.php
single-attachment-{slug}.php – For example, if the attachment slug is 
holiday, WordPress would look for 
single-attachment-holiday.php.
single-attachment.php
single.php
singular.php
index.php
As of WordPress 6.4, attachment pages are no longer enabled by default on new installations. Users can enable them with a plugin, so it is still good practice to test your theme and ensure it properly displays content when viewing an attachment page.
Embeds
The embed template file is used to render a post which is being embedded. Since 4.5, WordPress uses the following path:
embed-{post-type}-{post_format}.php – First, WordPress looks for a template for the specific post. For example, if its post type is 
post and it has the audio format, WordPress would look for 
embed-post-audio.php.
embed-{post-type}.php – If the post type is 
product, WordPress would look for 
embed-product.php.
embed.php – WordPress then falls back to embed
.php.
Finally, WordPress ultimately falls back to its own 
wp-includes/theme-compat/embed.php template.
Non-ASCII Character Handling
Since WordPress 4.7, any dynamic part of a template name which includes non-ASCII characters in its name actually supports both the un-encoded and the encoded form, in that order. You can choose which to use.
Here’s the page template hierarchy for a page named “Hello World 😀” with an ID of 
6:
page-hello-world-😀.php
page-hello-world-%f0%9f%98%80.php
page-6.php
page.php
singular.php
The same behaviour applies to post slugs, term names, and author nicenames.
Filter Hierarchy
The WordPress template system lets you filter the hierarchy. This means that you can insert and change things at specific points of the hierarchy. The filter (located in the 
get_query_template() function) uses this filter name: 
"{$type}_template" where 
$type is the template type.
Here is a list of all available filters in the template hierarchy:
embed_template
404_template
search_template
frontpage_template
home_template
privacypolicy_template
taxonomy_template
attachment_template
single_template
page_template
singular_template
category_template
tag_template
author_template
date_template
archive_template
index_template
Example
For example, let’s take the default author hierarchy:
author-{nicename}.php
author-{id}.php
author.php
To add 
author-{role}.php before 
author.php, we can manipulate the actual hierarchy using the ‘author_template’ template type. This allows a request for /author/username where username has the role of editor to display using author-editor.php if present in the current themes directory.
function author_role_template( $templates = '' ) {
	$author = get_queried_object();
	$role   = $author->roles[0];
	if ( ! is_array( $templates ) && ! empty( $templates ) ) {
		$templates = locate_template( array( "author-$role.php", $templates ), false );
	} elseif ( empty( $templates ) ) {
		$templates = locate_template( "author-$role.php", false );
	} else {
		$new_template = locate_template( array( "author-$role.php" ) );
		if ( ! empty( $new_template ) ) {
			array_unshift( $templates, $new_template );
		}
	}
	return $templates;
}
add_filter( 'author_template', 'author_role_template' );
Changelog:
Updated 2022-02-15. Added a notice explaining that the template hierarchy is the same for classic and block themes, but that the examples uses .php files and block themes use .html files.

Template Tags
Template tags are used within themes to retrieve content from your database. The content could be anything from a blog title to a complete sidebar. Template tags are the preferred method to pull content into your theme because:
they can print dynamic content;
they can be used in multiple theme files; and
they separate the theme into smaller, more understandable, sections.
What is a Template Tag?
A template tag is simply a piece of code that tells WordPress to get something from the database. It is broken up into three components:
A PHP code tag
A WordPress function
Optional parameters
You can use a template tag to call another theme file or some information from the database.
For example, the template tag 
get_header() tells WordPress to get the 
header.php file and include it in the current theme file. Similarly, 
get_footer() tells WordPress to get the footer.php file.
There are also other kinds of template tags:
the_title() – tells WordPress to get the title of the page or post from the database and include it.
bloginfo( 'name' ) – tells WordPress to get the blog title out of the database and include it in the template file.
If you look closely at the last example, you will also see that there is a parameter between the parenthesis. Parameters let you do two things:
ask for specific pieces of information and
format the information in a certain way.
Parameters are covered extensively below, but it’s useful to be aware that you can send WordPress-specific instructions for how you want the data presented.
Why Use Template Tags
By encapsulating all of the code for a particular chunk of content, template tags make it very easy to include various pieces of a template in a theme file and also to maintain the theme.
It is far easier to create one 
header.php file and have all of your theme templates like 
single.php, 
page.php, 
front-page.php, etc. reference that one theme file using 
get_header() than copying and pasting the code into each theme file. It also makes maintenance easier. Whenever you make a change in your 
header.php file, the change is automatically carried over into all of your other theme files.
Another reason to use template tags is to display dynamic data, i.e. data from the database. In your header, you could manually include the 
title tag, like so:
<title>My Personal Website</title>
However, doing this means manually editing your theme any time you want to change the title of your website. Instead, it’s easier to include the 
bloginfo( 'name' ) template tag, which automatically fetch the site title from the database. Now, you can change the title of your site in WordPress, rather than having to hard code your theme templates.
How to Use Template Tags
Using template tags is very simple. In any template file you can use a template tag by simply printing one line of php code to call the template tag. Printing the header.php file is as simple as:
get_header();
Parameters
Some template tags let you pass parameters. Parameters are extra pieces of information that determine what is retrieved from the database.
For example, the 
bloginfo() template tag allows you to give it a parameter telling WordPress the specific piece of information you want. To print the blog name, you just pass along the parameter “name,” like so:
bloginfo( 'name' );
To print the version of WordPress that the blog is running on, you would pass a parameter of “version”:
bloginfo( 'version' );
For each template tag, the parameters differ. A list of the parameters and what they can do can be found on specific template tag pages located throughout the code reference.
Using Template Tags Within the Loop
Many template tags work within the WordPress Loop. This means that they are included in the template files as part of the php “loop” that generates the pages users see based upon the instructions inside of the loop.
The WordPress loop begins with:
if ( have_posts() ) :
	while ( have_posts() ) :
		the_post();
Template tags that work within the loop must be in the middle area, before the ending section of the loop below:
	endwhile;
else :
	_e( 'Sorry, no posts matched your criteria.', 'devhub' );
endif;
Some of template tags that need to be inside of the loop include
the_content()
the_excerpt()
next_post()
previous_post()
The main reason why some functions require the loop is because they require the global post object to be set.
If the template tag you want to use doesn’t have to be within the loop
wp_list_cats()
wp_list_pages()
then you can put it in any file you’d like, for instance in the sidebar, header, or footer template files.
These are functions that typically do not require the global post object.
See Also
Conditional Tags
Complete list of Template Tags
Plugin API Hooks

The Loop
The Loop is the default mechanism WordPress uses for outputting posts through a theme’s template files. How many posts are retrieved is determined by the number of posts to show per page defined in the Reading settings. Within the Loop, WordPress retrieves each post to be displayed on the current page and formats it according to your theme’s instructions.
The Loop extracts the data for each post from the WordPress database and inserts the appropriate information in place of each template tag. Any HTML or PHP code in The Loop will be processed for each post.
To put it simply, the Loop is true to its name: it loops through each post retrieved for the current page one at a time and performs the action specified in your theme.
You can use the Loop for a number of different things, for example to:
display post titles and excerpts on your blog’s homepage;
display the content and comments on a single post;
display the content on an individual page using template tags; and
display data from Custom Post Types and Custom Fields.
You can customize the Loop across your template files to display and manipulate different content.
The Loop in Detail
The basic loop is:
<?php
if ( have_posts() ) :
    while ( have_posts() ) : the_post();
        // Display post content
    endwhile;
endif;
?>
This loop says that when there are posts, loop through and display the posts. Broken down into more detail:
The 
have_posts() function checks whether there are any posts.
If there are posts, a 
while loop continues to execute as long as the condition in the parenthesis is logically true. As long as 
have_posts() continues to be true, the loop will continue.
Using The Loop
The Loop should be placed in 
index.php, and in any other templates which are used to display post information. Because you do not want to duplicate your header over and over, the loop should always be placed after the call to 
get_header(). For example:
<?php
get_header();
if ( have_posts() ) :
    while ( have_posts() ) : the_post();
        // Display post content
    endwhile;
endif;
?>
In the above example, the end of the Loop is shown with an 
endwhile and 
endif. The Loop must always begin with the same 
if and 
while statements, as mentioned above and must end with the same end statements.
Any template tags that you wish to apply to all posts must exist between the beginning and ending statements.
You can include a custom 404 “not found” message that will be displayed if no posts matching the specified criteria are available. The message must be placed between the 
endwhile and 
endif statements, as seen in examples below.
An extremely simple 
index.php file would look like:
<?php
get_header();
if ( have_posts() ) :
    while ( have_posts() ) : the_post();
        the_content();
    endwhile;
else :
    _e( 'Sorry, no posts matched your criteria.', 'textdomain' );
endif;
get_sidebar();
get_footer();
?>
What the Loop Can Display
The Loop can display a number of different elements for each post. For example, some common template tags used in many themes are:
next_post_link() – a link to the post published chronologically after the current post
previous_post_link() – a link to the post published chronologically before the current post
the_category() – the category or categories associated with the post or page being viewed
the_author() – the author of the post or page
the_content() – the main content for a post or page
the_excerpt() – the first 55 words of a post’s main content followed by an ellipsis (…) or read more link that goes to the full post. You may also use the “Excerpt” field of a post to customize the length of a particular excerpt.
the_ID() – the ID for the post or page
the_meta() – the custom fields associated with the post or page
the_shortlink() – a link to the page or post using the url of the site and the ID of the post or page
the_tags() – the tag or tags associated with the post
the_title() – the title of the post or page
the_time() – the time or date for the post or page. This can be customized using standard php date function formatting.
You can also use conditional tags, such as:
is_home() – Returns true if the current page is the homepage
is_admin() – Returns true if inside Administration Screen, false otherwise
is_single() – Returns true if the page is currently displaying a single post
is_page() – Returns true if the page is currently displaying a single page
is_page_template() – Can be used to determine if a page is using a specific template, for example: 
is_page_template('about-page.php')
is_category() – Returns true if page or post has the specified category, for example: 
is_category('news')
is_tag() – Returns true if a page or post has the specified tag
is_author() – Returns true if inside author’s archive page
is_search() – Returns true if the current page is a search results page
is_404() – Returns true if the current page does not exist
has_excerpt() – Returns true if the post or page has an excerpt
Examples
Let’s take a look at some examples of the Loop in action:
Basic Examples
Blog Archive
Most blogs have a blog archive page, which can show a number of things including the post title, thumbnail, and excerpt. The example below shows a simple loop that checks to see if there are any posts and, if there are, outputs each post’s title, thumbnail, and excerpt. If no posts exists, it displays the message in parentheses.
<?php
if ( have_posts() ) :
    while ( have_posts() ) : the_post();
        the_title( '<h2>', '</h2>' );
        the_post_thumbnail();
        the_excerpt();
    endwhile;
else:
    _e( 'Sorry, no posts matched your criteria.', 'textdomain' );
endif;
?>
Individual Post
In WordPress, each post has its own page, which displays the relevant information for that post. Template tags allow you to customize which information you want to display.
In the example below, the loop outputs the post’s title and content. You could use this example in a post or page template file to display the most basic information about the post. You could also customize this template to add more data to the post, for example the category.
<?php
if ( have_posts() ) :
    while ( have_posts() ) : the_post();
        the_title( '<h1>', '</h1>' );
        the_content();
    endwhile;
else:
    _e( 'Sorry, no pages matched your criteria.', 'textdomain' );
endif;
?>
Intermediate Examples
Style Posts from Some Categories Differently
The example below does a couple of things:
First, it displays each post with its title, time, author, content, and category, similar to the individual post example above.
Next, it makes it possible for posts with the category ID of “3” to be styled differently, utilizing the 
in_category() template tag.
Code comments in this example provide details throughout each stage of the loop:
<?php
// Start the Loop.
if ( have_posts() ) :
    while ( have_posts() ) : the_post();
        /* * See if the current post is in category 3.
          * If it is, the div is given the CSS class "post-category-three".
          * Otherwise, the div is given the CSS class "post".
        */
        if ( in_category( 3 ) ) : ?>
        <div class="post-category-three">
        <?php else : ?>
        <div class="post">
        <?php endif; 
            // Display the post's title.
            the_title( '<h2>', ';</h2>' ); 
            // Display a link to other posts by this posts author.
            printf( __( 'Posted by %s', 'textdomain' ), get_the_author_posts_link() );
            // Display the post's content in a div.
            ?>
            <div class="entry">
                <?php the_content() ?>
             </div>
            <?php
            // Display a comma separated list of the post's categories.
            _e( 'Posted in ', 'textdomain' ); the_category( ', ' ); 
        // closes the first div box with the class of "post" or "post-cat-three"
       ?>
       </div>
    <?php
    // Stop the Loop, but allow for a "if not posts" situation
    endwhile; 
else :
    /*
      * The very first "if" tested to see if there were any posts to
      * display. This "else" part tells what do if there weren't any.
     */
     _e( 'Sorry, no posts matched your criteria.', 'textdomain' );
// Completely stop the Loop.
 endif;
?>
Multiple Loops
In some situations, you may need to use more than one loop. For example you may want to display the titles of the posts in a table of content list at the top of the page and then display the content further down the page. Since the query isn’t being changed we simply need to rewind the loop when we need to loop through the posts for a second time. For that we will use the function rewind_posts() .
Using rewind_posts
You can use 
rewind_posts() to loop through the same query a second time. This is useful if you want to display the same query twice in different locations on a page.
Here is an example of 
rewind_posts() in use:
<?php
// Start the main loop
if ( have_posts() ) :
    while ( have_posts() ) : the_post();
        the_title();
    endwhile;
endif;
// Use rewind_posts() to use the query a second time.
rewind_posts();
// Start a new loop
while ( have_posts() ) : the_post();
    the_content();
endwhile;
?>
Creating secondary queries and loops
Using two loops with the same query was relatively easy but not always what you will need. Instead, you will often want to create a secondary query to display different content on the template. For example, you might want to display two groups of posts on the same page, but do different things to each group. A common example of this, as shown below, is displaying a single post with a list of posts from the same category below the single post.
<?php
// The main query.
if ( have_posts() ) :
    while ( have_posts() ) : the_post();
        the_title();
        the_content();
    endwhile;
else :
    // When no posts are found, output this text.
    _e( 'Sorry, no posts matched your criteria.' );
endif;
wp_reset_postdata();                                                        
/*
 * The secondary query. Note that you can use any category name here. In our example,
 * we use "example-category".
 */
$secondary_query = new WP_Query( 'category_name=example-category' );        
// The second loop.
if ( $secondary_query->have_posts() )
    echo '<ul>';
    while ( $secondary_query->have_posts() ) : $secondary_query->the_post();
        the_title( '<li>', '</li>' );
     endwhile;
     echo '</ul>';
endif;
wp_reset_postdata();
?>
As you can see in the example above, we first display a regular loop. Then we define a new variable that uses 
WP_Query to query a specific category; in our case, we chose the 
example-category slug.
Note that the regular loop in the example above has one difference: it calls 
wp_reset_postdata() to reset the post data. Before you can use a second loop, you need to reset the post data. There are two ways to do this:
By using the 
rewind_posts() function; or
By creating new query objects.
Resetting multiple loops
It’s important when using multiple loops in a template that you reset them. Not doing so can lead to unexpected results due to how data is stored and used within the global 
$post variable. There are three main ways to reset the loop depending on the way they are called.
wp_reset_postdata()
wp_reset_query()
rewind_posts()
Using wp_reset_postdata
Use 
wp_reset_postdata() when you are running custom or multiple loops with 
WP_Query. This function restores the global 
$post variable to the current post in the main query. If you’re following best practices, this is the most common function you will use to reset loops.
To properly use this function, place the following code after any loops with 
WP_Query:
<?php wp_reset_postdata(); ?>
Here is an example of a loop using 
WP_Query that is reset with 
wp_reset_postdata().
 <?php
// Example argument that defines three posts per page.
$args = array( 'posts_per_page' => 3 ); 
// Variable to call WP_Query.
$the_query = new WP_Query( $args ); 
if ( $the_query->have_posts() ) :
    // Start the Loop
    while ( $the_query->have_posts() ) : $the_query->the_post();
        the_title();
        the_excerpt();
    // End the Loop
    endwhile;
else:
// If no posts match this query, output this text.
    _e( 'Sorry, no posts matched your criteria.', 'textdomain' );
endif; 
wp_reset_postdata();
?>
Using wp_reset_query
Using 
wp_reset_query() restores the WP_Query and global 
$post data to the original main query. You MUST use this function to reset your loop if you use 
query_posts() within your loop. You can use it after custom loops with WP_Query because it actually calls 
wp_reset_postdata() when it runs. However, it’s best practice to use 
wp_reset_postdata() with any custom loops involving 
WP_Query.
query_posts() is not best practice and should be avoided if at all possible. Therefore, you shouldn’t have much use for 
wp_reset_query().
To properly use this function, place the following code after any loops with 
query_posts().
<?php wp_reset_query(); ?>

Theme Functions
Functions.php can be used by both classic themes, block themes, and child themes.
The 
functions.php file is where you add unique features to your WordPress theme. It can be used to hook into the core functions of WordPress to make your theme more modular, extensible, and functional.
What is 
functions.php?
The 
functions.php file behaves like a WordPress plugin, adding features and functionality to a WordPress site. You can use it to call WordPress functions and to define your own functions.
The same result can be produced using either a plugin or 
functions.php. If you are creating new features that should be available no matter what the website looks like, it is best practice to put them in a plugin.
There are advantages and tradeoffs to either using a WordPress plugin or using 
functions.php.
A WordPress plugin:
requires specific, unique header text;
is stored in wp-content/plugins, usually in a subdirectory;
only executes on page load when activated;
applies to all themes; and
should have a single purpose – for example, offer search engine optimization features or help with backups.
Meanwhile, a 
functions.php file:
requires no unique header text;
is stored in theme’s subdirectory in wp-content/themes;
executes only when in the active theme’s directory;
applies only to that theme (if the theme is changed, the features can no longer be used); and
can have numerous blocks of code used for many different purposes.
Each theme has its own functions file, but only code in the active theme’s 
functions.php is actually run. If your theme already has a functions file, you can add code to it. If not, you can create a plain-text file named 
functions.php to add to your theme’s directory, as explained below.
A child theme can have its own 
functions.php file. Adding a function to the child functions file is a risk-free way to modify a parent theme. That way, when the parent theme is updated, you don’t have to worry about your newly added function disappearing.
Although the child theme’s 
functions.php is loaded by WordPress right before the parent theme’s 
functions.php, it does not override it. The child theme’s 
functions.php can be used to augment or replace the parent theme’s functions. Similarly, 
functions.php is loaded after any plugin files have loaded.
With 
functions.php you can:
Use WordPress hooks. For example, with the 
excerpt_length filter you can change your post excerpt length (from default of 55 words).
Enable WordPress features with 
add_theme_support(). For example, turn on post thumbnails, post formats, and navigation menus.
Define functions you wish to reuse in multiple theme template files.
In WordPress, naming conflicts can occur when two or more functions, classes, or variables have the same name. This can cause errors or unexpected behavior in a WordPress site. It is the responsibility of both the theme developer and plugin developer to avoid naming conflicts in their respective code.
Theme developers should ensure that their functions, classes, and variables have unique names that do not conflict with those used by WordPress core or other plugins. They should also prefix their function and class names with a unique identifier, such as the theme name or abbreviation, to minimize the chances of a naming conflict.
Examples
Below are a number of examples that you can use in your functions.php file to support various features. Each of these examples are allowed in your theme if you choose to submit it to the WordPress.org theme directory.
Theme Setup
A number of theme features should be included within a “setup” function that runs initially when your theme is activated. As shown below, each of these features can be added to your 
functions.php file to activate recommended WordPress features.
It’s important to namespace your functions with your theme name. All examples below use 
myfirsttheme_ as their namespace, which should be customized based on your theme name.
To create this initial function, start a new function entitled 
myfirsttheme_setup(), like so:
if ( ! function_exists( 'myfirsttheme_setup' ) ) :
/**
 * Sets up theme defaults and registers support for various WordPress  
 * features.
 *
 * It is important to set up these functions before the init hook so
 * that none of these features are lost.
 *
 *  @since MyFirstTheme 1.0
 */
function myfirsttheme_setup() { ... }
Note: In the above example, the function myfirsttheme_setup is started but not closed out. Be sure to close out your functions.
Automatic Feed Links
Automatic feed links enables post and comment RSS feeds by default. These feeds will be displayed in 
<head> automatically. They can be called using 
add_theme_support() in classic themes. This feature is automatically enabled for block themes, and does not need to be included during theme setup.
add_theme_support( 'automatic-feed-links' );
Navigation Menus
In classic themes, custom navigation menus allow users to edit and customize menus in the Menus admin panel, giving users a drag-and-drop interface to edit the various menus in their theme.
You can set up multiple menus in 
functions.php. They can be added using 
register_nav_menus() and inserted into a theme using 
wp_nav_menu(), as discussed later in this handbook. If your theme will allow more than one menu, you should use an array. While some themes will not have custom navigation menus, it is recommended that you allow this feature for easy customization.
register_nav_menus( array(
    'primary'   => __( 'Primary Menu', 'myfirsttheme' ),
    'secondary' => __( 'Secondary Menu', 'myfirsttheme' )
) );
Each of the menus you define can be called later using 
wp_nav_menu() and using the name assigned (i.e. primary) as the 
theme_location parameter.
In block themes, you use the navigation block instead.
Load Text Domain
Themes can be translated into multiple languages by making the strings in your theme available for translation. To do so, you must use 
load_theme_textdomain(). For more information on making your theme available for translation, read the internationalization section.
load_theme_textdomain( 'myfirsttheme', get_template_directory() . '/languages' );
Post Thumbnails
Post thumbnails and featured images allow your users to choose an image to represent their post. Your theme can decide how to display them, depending on its design. For example, you may choose to display a post thumbnail with each post in an archive view. Or, you may want to use a large featured image on your homepage. This feature is automatically enabled for block themes, and does not need to be included during theme setup.
add_theme_support( 'post-thumbnails' );
Post Formats
Post formats allow users to format their posts in different ways. This is useful for allowing bloggers to choose different formats and templates based on the content of the post. 
add_theme_support() is also used for Post Formats. This is recommended.
add_theme_support( 'post-formats',  array( 'aside', 'gallery', 'quote', 'image', 'video' ) );
Learn more about post formats.
Theme support in block themes
In block themes, HTML5 markup as well as the following theme supports are enabled automatically:
add_theme_support( 'post-thumbnails' );
add_theme_support( 'responsive-embeds' );
add_theme_support( 'editor-styles' );
add_theme_support( 'automatic-feed-links' );
Initial Setup Example
Including all of the above features will give you a 
functions.php file like the one below. Code comments have been added for future clarity.
As shown at the bottom of this example, you must add the required 
add_action() statement to ensure the 
myfirsttheme_setup function is loaded.
if ( ! function_exists( 'myfirsttheme_setup' ) ) :
	/**
	 * Sets up theme defaults and registers support for various
	 * WordPress features.
	 *
	 * Note that this function is hooked into the after_setup_theme
	 * hook, which runs before the init hook. The init hook is too late
	 * for some features, such as indicating support post thumbnails.
	 */
	function myfirsttheme_setup() {
    /**
	 * Make theme available for translation.
	 * Translations can be placed in the /languages/ directory.
	 */
		load_theme_textdomain( 'myfirsttheme', get_template_directory() . '/languages' );
		/**
		 * Add default posts and comments RSS feed links to <head>.
		 */
		add_theme_support( 'automatic-feed-links' );
		/**
		 * Enable support for post thumbnails and featured images.
		 */
		add_theme_support( 'post-thumbnails' );
		/**
		 * Add support for two custom navigation menus.
		 */
		register_nav_menus( array(
			'primary'   => __( 'Primary Menu', 'myfirsttheme' ),
			'secondary' => __( 'Secondary Menu', 'myfirsttheme' ),
		) );
		/**
		 * Enable support for the following post formats:
		 * aside, gallery, quote, image, and video
		 */
		add_theme_support( 'post-formats', array( 'aside', 'gallery', 'quote', 'image', 'video' ) );
	}
endif; // myfirsttheme_setup
add_action( 'after_setup_theme', 'myfirsttheme_setup' );
Content Width
In classic themes, a content width is added to your 
functions.php file to ensure that no content or assets break the container of the site. The content width sets the maximum allowed width for any content added to your site, including uploaded images. In the example below, the content area has a maximum width of 800 pixels. No content will be larger than that.
if ( ! isset ( $content_width) ) {
    $content_width = 800;
}
Themes that include a theme.json configuration file does not need to include the variable in functions.php. Instead, the content width is added to the layout setting in theme.json. You can learn more about using theme.json in the advanced section.
Other Features
There are other common features you can include in 
functions.php. Listed below are some of the most common features. Click through and learn more about each of these features.
Custom Headers -Classic themes
Sidebars (widget areas) -Classic themes
Custom Background -Classic themes
Title tag -Classic themes
Add Editor Styles
HTML5 -Classic themes
Your functions.php File
If you choose to include all the functions listed above, this is what your functions.php might look like. It has been commented with references to above.
/**
 * MyFirstTheme's functions and definitions
 *
 * @package MyFirstTheme
 * @since MyFirstTheme 1.0
 */
/**
 * First, let's set the maximum content width based on the theme's
 * design and stylesheet.
 * This will limit the width of all uploaded images and embeds.
 */
if ( ! isset( $content_width ) ) {
	$content_width = 800; /* pixels */
}
if ( ! function_exists( 'myfirsttheme_setup' ) ) :
	/**
	 * Sets up theme defaults and registers support for various
	 * WordPress features.
	 *
	 * Note that this function is hooked into the after_setup_theme
	 * hook, which runs before the init hook. The init hook is too late
	 * for some features, such as indicating support post thumbnails.
	 */
	function myfirsttheme_setup() {
		/**
		 * Make theme available for translation.
		 * Translations can be placed in the /languages/ directory.
		 */
		load_theme_textdomain( 'myfirsttheme', get_template_directory() . '/languages' );
		/**
		 * Add default posts and comments RSS feed links to <head>.
		 */
		add_theme_support( 'automatic-feed-links' );
		/**
		 * Enable support for post thumbnails and featured images.
		 */
		add_theme_support( 'post-thumbnails' );
		/**
		 * Add support for two custom navigation menus.
		 */
		register_nav_menus( array(
			'primary'   => __( 'Primary Menu', 'myfirsttheme' ),
			'secondary' => __( 'Secondary Menu', 'myfirsttheme' ),
		) );
		/**
		 * Enable support for the following post formats:
		 * aside, gallery, quote, image, and video
		 */
		add_theme_support( 'post-formats', array( 'aside', 'gallery', 'quote', 'image', 'video' ) );
	}
endif; // myfirsttheme_setup
add_action( 'after_setup_theme', 'myfirsttheme_setup' );

Tools & Resources
Whether you’re building your very first theme or your tenth, the following resources are meant to help ease the process. Keep in mind that there are various community tools not mentioned here as well but that still might aid in your efforts.
Block themes
A block theme is a type of WordPress theme built using blocks. You can read more about these themes in the Block Theme section.
Create Block Theme plugin
This plugin was created by various community members. This tool can create standalone block themes and child themes, depending on your needs. Here are the high-level steps:
Install and activate the Create Block Theme plugin. You will also need to be running the latest version of the Gutenberg plugin.
Make changes to your site design using the Customizer and Site Editor.
Edit your templates using the Site Editor. For some things, you might need to edit the template files again later.
In the WordPress Admin Dashboard, under Appearance there will be a new page called “Create Block Theme”. You can add the details for the theme here. These details will be used in the style.css file.
Click the “Create Block Theme” button. From there, a zip file will be downloaded which will contain all the files for your theme.
Theme Generator
This tool was created by Carolina Nymark and it allows you to create three different types of themes to start from:
No Code: for non-developers who want to start from a blank theme and build directly in the Site Editor.
Empty: for developers to make their own with six templates and a theme.json with empty settings for you to complete.
Basic: for developers to explore with six templates, two template parts, three block patterns, and two custom block styles alongside some initial theme.json settings.
Advanced: for developers to explore with seven templates, five template parts, seven patterns, various block styles, and a more robust theme.json. It’s common to want to remove some of the examples.
Comparison Chart
Tool
Child theme options?
Template creation?
Theme.json Controls
Demo content
Create Block Theme plugin
Yes
Yes
No
No
Theme Generator
No
Yes
Yes
Yes
Classic themes
A classic theme is built with PHP templates, functions.php, and more. You can read more about these themes in the Classic Theme section.
The _s (Underscores) starter theme is a tool for initializing and creating a classic theme.
Tools
WordPress Coding Standards for PHP_CodeSniffer
This project is a collection of PHP_CodeSniffer rules (sniffs) that are used to validate code developed for WordPress, but can also be used when developing themes and plugins. They encompass coding style along with established best practices regarding interoperability, translatability, and security in the WordPress ecosystem, according to the official WordPress Coding Standards.
WordPress Coding Standards for PHP_CodeSniffer
The WPThemeReview Standards for PHP_CodeSniffer are a collection of sniffs that aim to automate the code analysis part of the Theme Review Process as much as possible using static code analysis.
The WPThemeReview Standards require the WordPress Coding Standards.
WPThemeReview Standards for PHP_CodeSniffer
Theme Check Plugin
The theme check plugin is an easy way to test your theme and make sure it’s up to spec with the latest theme review standards. With it, you can run all the same automated testing tools on your theme that WordPress.org uses for theme submissions. This allows you to resolve any issues that might come up before trying to submit your theme to the theme repository.
Training material
Simple Site Design and Site Editing: Part 1, Part 2, Part 3
Anatomy of a Block Theme
Creating a landing page with a block theme
Building a home page with a block theme
Using Schema with WordPress theme.json
Create a Basic Child Theme for Block Themes
Find more theme lessons on learn.wordpress.org.

Advanced Usage
The customize API is actively developed; this page contains additional more advanced topics. Additional discussion of advanced topics cab be found by searching the archives for the #core-customize channel in Slack.
Allow Non-administrators to Access the Customizer
Customizer access is controlled by the customize meta capability (mapped to edit_theme_options by default), which is assigned only to administrators by default. This allows for wider use of the Customizer’s extensive capability-access options, which are built into panels, sections, and settings. Additionally, this makes it possible to allow non-administrators to use the customizer for, for example, customizing posts. This change is an important step toward expanding the scope of the Customizer beyond themes.
<?php
function allow_users_who_can_edit_posts_to_customize( $caps, $cap, $user_id ) {
	$required_cap = 'edit_posts';
	if ( 'customize' === $cap && user_can( $user_id, $required_cap ) ) {
		$caps = array( $required_cap );
	}
	return $caps;
}
add_filter( 'map_meta_cap', 'allow_users_who_can_edit_posts_to_customize', 10, 3 );
Note that it is currently necessary to manually add links to the Customizer in the admin menu, admin bar, or elsewhere if you are granting the customize meta capability to non-administrator users.

Customizer Objects
The Customize API is object-oriented. There are four main types of Customizer objects: Panels, Sections, Settings, and Controls. Settings associate UI elements (controls) with settings that are saved in the database. Sections are UI containers for controls, to improve their organization. Panels are containers for sections, allowing multiple sections to be grouped together.
Each Customizer object is represented by a PHP class, and all of the objects are managed by the Customize Manager object, WP_Customize_Manager.
To add, remove, or modify any Customizer object, and to access the Customizer Manager, use the 
customize_register hook:
function themeslug_customize_register( $wp_customize ) {
  // Do stuff with $wp_customize, the WP_Customize_Manager object.
}
add_action( 'customize_register', 'themeslug_customize_register' );
The Customizer Manager provides add_, get_, and remove_ methods for each Customizer object type; each works with an id. The get_ methods allow for direct modification of parameters specified when adding a control.
add_action('customize_register','my_customize_register');
function my_customize_register( $wp_customize ) {
  $wp_customize->add_panel();
  $wp_customize->get_panel();
  $wp_customize->remove_panel();
  $wp_customize->add_section();
  $wp_customize->get_section();
  $wp_customize->remove_section();
  $wp_customize->add_setting();
  $wp_customize->get_setting();
  $wp_customize->remove_setting();
  $wp_customize->add_control();
  $wp_customize->get_control();
  $wp_customize->remove_control();
}
Note: themes generally should not modify core sections and panels with the get methods, since themes should not modify core, theme-agnostic functionality. Plugins are encouraged to use these functions where necessary. Themes should not “reorganize” customizer sections that aren’t added by the theme.
Settings
Settings handle live-previewing, saving, and sanitization of your customizer objects. Each setting is managed by a control object. There are several parameters available when adding a new setting:
$wp_customize->add_setting( 'setting_id', array(
  'type' => 'theme_mod', // or 'option'
  'capability' => 'edit_theme_options',
  'theme_supports' => '', // Rarely needed.
  'default' => '',
  'transport' => 'refresh', // or postMessage
  'sanitize_callback' => '',
  'sanitize_js_callback' => '', // Basically to_json.
) );
Important: Do not use a setting ID that looks like 
widget_*, 
sidebars_widgets[*], 
nav_menu[*], or 
nav_menu_item[*]. These setting ID patterns are reserved for widget instances, sidebars, nav menus, and nav menu items respectively. If you need to use “widget” in your setting ID, use it as a suffix instead of a prefix, for example “
homepage_widget”.
There are two primary types of settings: options and theme modifications. Options are stored directly in the wp_options table of the WordPress database and apply to the site regardless of the active theme. Themes should rarely if ever add settings of the option type. Theme mods, on the other hand, are specific to a particular theme. Most theme options should be theme_mods. For example, a custom CSS plugin could register a custom theme css setting as a theme_mod, allowing each theme to have a unique set of CSS rules without losing the CSS when switching themes then switching back.
Theme_mod vs. option setting type example.
It is usually most important to set the default value of the setting as well as its sanitization callback, which will ensure that no unsafe data is stored in the database. Typical theme usage:
$wp_customize->add_setting( 'accent_color', array(
  'default' => '#f72525',
  'sanitize_callback' => 'sanitize_hex_color',
) );
Typical plugin usage:
$wp_customize->add_setting( 'myplugin_options[color]', array(
  'type' => 'option',
  'capability' => 'manage_options',
  'default' => '#ff2525',
  'sanitize_callback' => 'sanitize_hex_color',
) );
Note that the Customizer can handle options stored as keyed arrays for settings using the option type. This allows multiple settings to be stored in a single option that isn’t a theme mod. To retrieve and use the values of your Customizer options, use 
get_theme_mod() and 
get_option() with the setting id:
function my_custom_css_output() {
  echo '<style type="text/css" id="custom-theme-css">' .
  get_theme_mod( 'custom_theme_css', '' ) . '</style>';
  echo '<style type="text/css" id="custom-plugin-css">' .
  get_option( 'custom_plugin_css', '' ) . '</style>';
}
add_action( 'wp_head', 'my_custom_css_output');
Note that the second argument for 
get_theme_mod() and 
get_option() is the default value, which should match the default you set when adding the setting.
Controls
Controls are the primary Customizer object for creating UI.  Specifically, every control must be associated with a setting, and that setting will save user-entered data from the control to the database (in addition to displaying it in the live-preview and sanitizing it). Controls can be added by the Customizer Manager and provide a robust set of UI options with minimal effort:
$wp_customize->add_control( 'setting_id', array(
  'type' => 'date',
  'priority' => 10, // Within the section.
  'section' => 'colors', // Required, core or custom.
  'label' => __( 'Date' ),
  'description' => __( 'This is a date control with a red border.' ),
  'input_attrs' => array(
    'class' => 'my-custom-class-for-js',
    'style' => 'border: 1px solid #900',
    'placeholder' => __( 'mm/dd/yyyy' ),
  ),
  'active_callback' => 'is_front_page',
) );
The most important parameter when adding a control is its type — this determines what type of UI the Customizer will display. Core provides several built-in control types:
<input> elements with any allowed type (see below)
checkbox
textarea
radio (pass a keyed array of values => labels to the 
choices argument)
select (pass a keyed array of values => labels to the 
choices argument)
dropdown-pages (use the 
allow_addition argument to allow users to add new pages from the control)
For any input type supported by the html 
input element, simply pass the type attribute value to the type parameter when adding the control. This allows support for control types such as 
text, 
hidden, 
number, 
range, 
url, 
tel, 
email, 
search, 
time, 
date, 
datetime, and 
week, pending browser support.
Controls must be added to a section before they will be displayed (and sections must contain controls to be displayed). This is done by specifying the section parameter when adding the control. Here is an example for adding a basic textarea control:
$wp_customize->add_control( 'custom_theme_css', array(
  'label' => __( 'Custom Theme CSS' ),
  'type' => 'textarea',
  'section' => 'custom_css',
) );
And here’s an example of a basic range (slider) control. Note that most browsers will not display the numeric value of this control because the range input type is designed for settings where the exact value is unimportant. If the numeric value is important, consider using the number type. The 
input_attrs parameter will map a keyed array of attributes => values to attributes on the input element, and can be used for purposes ranging from placeholder text to 
data- JavaScript-referenced data in custom scripts. For number and range controls, it allows us to set the minimum, maximum, and step values.
$wp_customize->add_control( 'setting_id', array(
  'type' => 'range',
  'section' => 'title_tagline',
  'label' => __( 'Range' ),
  'description' => __( 'This is the range control description.' ),
  'input_attrs' => array(
    'min' => 0,
    'max' => 10,
    'step' => 2,
  ),
) );
Core Custom Controls
If none of the basic control types suit your needs, you can easily create and add custom controls. Custom controls are explained more fully later in this post, but they are essentially subclasses of the base 
WP_Customize_Control object that allow any arbitrary html markup and functionality that you might need. Core features several built-in custom controls that allow developers to implement rich JavaScript-driven features with ease. A color picker control can be added as follows:
$wp_customize->add_control( new WP_Customize_Color_Control( $wp_customize, 'color_control', array(
  'label' => __( 'Accent Color', 'theme_textdomain' ),
  'section' => 'media',
) ) );
WordPress 4.1 and 4.2 also added support for any type of multimedia content, with the Media control. The media control implements the native WordPress media manager, allowing users to select files from their library or upload new ones. By specifying the 
mime_type parameter when adding the control, you can instruct the media library show to a specific type such as images or audio:
$wp_customize->add_control( new WP_Customize_Media_Control( $wp_customize, 'image_control', array(
  'label' => __( 'Featured Home Page Image', 'theme_textdomain' ),
  'section' => 'media',
  'mime_type' => 'image',
) ) );
$wp_customize->add_control( new WP_Customize_Media_Control( $wp_customize, 'audio_control', array(
  'label' => _( 'Featured Home Page Recording', 'theme_textdomain' ),
  'section' => 'media',
  'mime_type' => 'audio',
) ) );
Note that settings associated with 
WP_Customize_Media_Control save the associated attachment ID, while all other media-related controls (children of 
WP_Customize_Upload_Control) save the media file URL to the setting. More information is available on Make WordPress Core.
Additionally, WordPress 4.3 introduced the 
WP_Customize_Cropped_Image_Control, which provides an interface for cropping an image after selecting it. This is useful for instances where a particular aspect ratio is needed.
Sections
Sections are UI containers for Customizer controls. While you can add custom controls to the core sections, if you have more than a few options you may want to add one or more custom sections. Use the 
add_section method of the WP_Customize_Manager object to add a new section:
$wp_customize->add_section( 'custom_css', array(
  'title' => __( 'Custom CSS' ),
  'description' => __( 'Add custom CSS here' ),
  'panel' => '', // Not typically needed.
  'priority' => 160,
  'capability' => 'edit_theme_options',
  'theme_supports' => '', // Rarely needed.
) );
You only need to include fields that you want to override the default values of. For example, the default priority (order of appearance) is typically acceptable, and most sections shouldn’t require descriptive text if your options are self-explanatory. If you do want to change the location of your custom section, the priorities of the core sections are below:
Title
ID
Priority (Order)
Site Title & Tagline
title_tagline
20
Colors
colors
40
Header Image
header_image
60
Background Image
background_image
80
Menus (Panel)
nav_menus
100
Widgets (Panel)
widgets
110
Static Front Page
static_front_page
120
default
160
Additional CSS
custom_css
200
In most cases, sections can be added with only one or two parameters being specified. Here’s an example for adding a section for options that pertain to a theme’s footer:
// Add a footer/copyright information section.
$wp_customize->add_section( 'footer' , array(
  'title' => __( 'Footer', 'themename' ),
  'priority' => 105, // Before Widgets.
) );
Panels
The Customizer Panels API was introduced in WordPress 4.0, and allows developers to create an additional layer of hierarchy beyond controls and sections. More than simply grouping sections of controls, panels are designed to provide distinct contexts for the Customizer, such as Customizing Widgets, Menus, or perhaps in the future, editing posts. There is an important technical distinction between the section and panel objects.
Themes should not register their own panels in most cases. Sections do not need to be nested under a panel, and each section should generally contain multiple controls. Controls should also be added to the Sections that core provides, such as adding color options to the colors Section. Also make sure that your options are as streamlined and efficient as possible; see the WordPress philosophy. Panels are designed as contexts for entire features such as Widgets, Menus, or Posts, not as wrappers for generic sections. If you absolutely must use Panels, you’ll find that the API is nearly identical to that for Sections:
$wp_customize->add_panel( 'menus', array(
  'title' => __( 'Menus' ),
  'description' => $description, // Include html tags such as <p>.
  'priority' => 160, // Mixed with top-level-section hierarchy.
) );
$wp_customize->add_section( $section_id , array(
  'title' => $menu->name,
  'panel' => 'menus',
) );
Panels must contain at least one Section, which must contain at least one Control, to be displayed. As you can see in the above example, Sections can be added to Panels similarly to how Controls are added to Sections. However, unlike with controls, if the Panel parameter is empty when registering a Section, it will be displayed on the main, top-level Customizer context, as most sections should not be contained with a panel.
Custom Controls, Sections, and Panels
Custom Controls, Sections, and Panels can be easily created by subclassing the PHP objects associated with each Customizer object: 
WP_Customize_Control, 
WP_Customize_Section, and 
WP_Customize_Panel (this can also be done for 
WP_Customize_Setting, but custom settings are typically better implemented using custom setting types, as outlined in the next section). Here’s an example for a basic custom control:
class WP_New_Menu_Customize_Control extends WP_Customize_Control {
  public $type = 'new_menu';
  /**
  * Render the control's content.
  */
  public function render_content() {
  ?>
    <button class="button button-primary" id="create-new-menu-submit" tabindex="0"><?php _e( 'Create Menu' ); ?></button>
  <?php
  }
}
By subclassing the base control class, you can override any functionality with custom functionality or use the core functionality depending on your needs. The most common function to override is 
render_content() as it allows you to create custom UI from scratch with HTML. Custom Controls should be used with caution, however, as they may introduce UI that is inconsistent with the surrounding core UI and cause confusion for users. Custom Customizer objects can be added similarly to how default controls, sections, and panels are added:
$wp_customize->add_control(
  new WP_Customize_Color_Control(
    $wp_customize, // WP_Customize_Manager
    'accent_color', // Setting id
    array( // Args, including any custom ones.
      'label' => __( 'Accent Color' ),
      'section' => 'colors',
    )
  )
);
Parameters passed when adding controls are mapped to class variables within the control class, so you can add and use custom ones where certain parts of your custom object are different across different instances.
When creating custom Controls, Sections, or Panels, it is strongly recommended to reference the core code, in order to fully understand the available functionality that can be overridden. Core also includes examples of custom objects of each type. This can be found in wp-includes/class-wp-customize-control.php, wp-includes/class-wp-customize-section.php, and wp-includes/class-wp-customize-panel.php. There is also a JavaScript API for each Customizer object type, which can be extended with custom objects; see the Customizer JavaScript API section for more details.
Customizer UI Standards
Custom customizer controls, sections, and panels should match core UI practices wherever possible. This includes relying on standards from wp-admin, such as using the 
.button and 
.button-primary classes, for example. There are also a few standards specific to the customizer (as of WordPress 4.7):
White background colors are used only to indicate navigation and actionable items (such as inputs)
The general 
#eee background color provides visual contrast against the white elements
1px #ddd borders separate navigational elements from background margins and from each other
15px of spacing is provided between elements where visual separation is desired
4px borders are used on one side of a navigation element to show hover or focus, with a color of 
#0073aa
Customizer text uses 
color: #555d66, with 
#0073aa for hover and focus states on navigation elements
Custom Setting Types
By default, the Customizer supports saving settings as options or theme modifications. But this behavior can be easily overwritten to manually save and preview settings outside of the wp_options table of the WordPress database, or to apply other custom handling. To get started, specify a type other than option or theme_mod when adding your setting (you can use pretty much any string):
$wp_customize->add_setting( $nav_menu_setting_id, array(
  'type' => 'nav_menu',
  'default' => $item_ids,
) );
The setting will no longer be saved or previewed when its value is changed in the associated control. Now, you can use the 
customize_update_$setting->type and 
customize_preview_$setting->type actions to implement custom saving and previewing functionality. Here is an example for saving a menu item’s order property from the Menu Customizer project (the value of the setting is an ordered array of menu ids):
function menu_customizer_update_nav_menu( $value, $setting ) {
  $menu_id = str_replace( 'nav_menu_', '', $setting->id );
  // ...
  $i = 0;
  foreach( $value as $item_id ) { // $value is ordered array of item ids.
    menu_customizer_update_menu_item_order( $menu_id, $item_id, $i );
  $i++;
  }
}
add_action( 'customize_update_nav_menu', 'menu_customizer_update_nav_menu', 10, 2 );
And here is how the same plugin implements previewing for nav menu items (note that this example requires PHP 5.3 or higher):
function menu_customizer_preview_nav_menu( $setting ) {
  $menu_id = str_replace( 'nav_menu_', '', $setting->id );
  add_filter( 'wp_get_nav_menu_items', function( $items, $menu, $args ) use ( $menu_id, $setting ) {
    $preview_menu_id = $menu->term_id;
    if ( $menu_id == $preview_menu_id ) {
      $new_ids = $setting->post_value();
      foreach ( $new_ids as $item_id ) {
        $item = wp_setup_nav_menu_item( $item );
        $item->menu_order = $i;
        $new_items[] = $item;
        $i++;
      }
      return $new_items;
    } else {
      return $items;
    }
  }, 10, 3 );
}
add_action( 'customize_preview_nav_menu', 'menu_customizer_preview_nav_menu', 10, 2 );

JavaScript/Underscore.js-Rendered Custom Controls
WordPress 4.1 also added support for rendering JavaScript-heavy and/or high-quantity controls entirely with JavaScript. This allows for more dynamic behavior, especially related to dynamically-added controls. The core Color and Media controls currently leverage this API, and all core Controls will eventually use it in the future. The PHP-based control API is not going away, but in the future most controls will likely use the new API since it provides a faster experience for users and developers. Similar APIs for JS-templated Sections and Panels were introduced WordPress 4.3; however, there remain some gaps in the ease of dynamically-creating objects in JS as of WordPress 4.7, see #30741.
Registered Control Types
In order to introduce a concept of having one template for multiple Customizer controls of the same type, we needed to introduce a way to register a type of control with the Customize Manager. Previously, custom control objects were only encountered when custom controls were added using 
WP_Customize_Manager::add_control(). But detecting added control types to render one template per type wouldn’t allow new controls to be created dynamically if no other instances of that type were loaded. 
WP_Customize_Manager::register_control_type() solves this:
add_action( 'customize_register', 'prefix_customize_register' );
function prefix_customize_register( $wp_customize ) {
  // Define a custom control class, WP_Customize_Custom_Control.
  // Register the class so that its JS template is available in the Customizer.
  $wp_customize->register_control_type( 'WP_Customize_Custom_Control' );
}
All registered control types have their templates printed to the customizer by 
WP_Customize_Manager::print_control_templates().
Sending PHP Control Data to JavaScript
While Customizer control data has always been passed to the control JS models, and this has always been able to be extended, you’re much more likely to need to send data down when working with JS templates. Anything that you would want access to in 
render_content() in PHP will need to be exported to JavaScript to be accessible in your control template. 
WP_Customize_Control exports the following control class variables by default:
type
label
description
active (boolean state)
You can add additional parameters specific to your custom control by overriding 
WP_Customize_Control::to_json() in your custom control subclass. In most cases, you’ll want to call the parent class’ 
to_json() method also, to ensure that all core variables are exported as well. Here’s an example from the core color control:
public function to_json() {
  parent::to_json();
  $this->json['statuses'] = $this->statuses;
  $this->json['defaultValue'] = $this->setting->default;
}
JS/Underscore Templating
Once you’ve registered your custom control class as a control type and exported any custom class variables, you can create the template that will render the control UI. You’ll override 
WP_Customize_Control::content_template() (empty by default) as a replacement for 
WP_Customize_Control::render_content(). Render content is still called, so be sure to override it with an empty function in your subclass as well.
Underscore-style custom control templates are very similar to PHP. As more and more of WordPress core becomes JavaScript-driven, these templates are becoming increasingly more common. Some sample template code in core can be found in media, revisions, the theme browser, and even in the Twenty Fifteen theme, where a JS template is used to both save the color scheme data and instantly preview color scheme changes in the Customizer. The best way to learn how these templates work is to study similar code in core and, accordingly, here is a brief example:
class WP_Customize_Color_Control extends WP_Customize_Control {
  public $type = 'color';
// ...
  /**
   * Render a JS template for the content of the color picker control.
   */
  public function content_template() {
    ?>
    <# var defaultValue = '';
    if ( data.defaultValue ) {
      if ( '#' !== data.defaultValue.substring( 0, 1 ) ) {
        defaultValue = '#' + data.defaultValue;
      } else {
        defaultValue = data.defaultValue;
      }
      defaultValue = ' data-default-color=' + defaultValue; // Quotes added automatically.
    } #>
    <label>
      <# if ( data.label ) { #>
        <span class="customize-control-title">{{{ data.label }}}</span>
      <# } #>
      <# if ( data.description ) { #>
        <span class="description customize-control-description">{{{ data.description }}}</span>
      <# } #>
      <div class="customize-control-content">
        <input class="color-picker-hex" type="text" maxlength="7" placeholder="<?php esc_attr_e( 'Hex Value' ); ?>" {{ defaultValue }} />
      </div>
    </label>
    <?php
  }
}
In the above template for the core custom color control, you can see that after the closing PHP tag, we have a JS template.  notation is used around statements to be evaluated – in most cases, this is used for conditionals. All of the control instance data that we exported to JS is stored in the 
data object, and we can print a variable using double (escaped) or triple (unescaped) brace notation 
{{ }}. As I said before, the best way to get the hang of writing controls like this is to read through existing examples. 
WP_Customize_Upload_Control was recently updated to leverage this API as well, integrating nicely with the way the media manager is implemented, and squeezing a ton of functionality out of a minimal amount of code. If you want some really good practice, try converting some of the other core controls to use this API – and submit patches to core too, of course!
Putting the pieces together
Here’s a summary of what’s needed to leverage the new API in a custom customizer control subclass:
Make your render_content() function empty (but it does need to exist to override the default one).
Create a new function, content_template(), and put the old contents of render_content() there.
Add any custom class variables that are needed for the control to be exported to the JavaScript in the browser (the JSON data) by modifying the to_json() function (see WP_Customize_Color_Control for an example).
Convert the PHP from render_content() into a JS template, using  around JS statements to evaluate and {{ }} around variables to print. PHP class variables are available in the data object; for example, the label can be printed with {{ data.label }}.
Register the custom control class/type. This critical step tells the Customizer to print the template for this control. This is distinct from just printing templates for all controls that were added because the ideas are that many instances of this control type could be rendered from one template, and that any registered control types would be available for dynamic control-creation in the future. Just do something like $wp_customize->register_control_type( 'WP_Customize_Color_Control' );.
The PHP-only parts of the Customize API are still fully supported and perfectly fine to use. But given long term goals for making the customizer more flexible for doing things like switching themes in the customizer without a pageload, it is strongly encouraged to use JS/Underscore templates for all custom customizer objects where feasible.

The Customizer JavaScript API
In WordPress 4.1, newly-expanded JavaScript APIs were introduced for all customizer objects. The entire JavaScript API is currently located in a single file, wp-admin/js/customize-controls.js, which contains models for all objects, core custom controls, and more.
Preview JS and Controls JS
The customizer app is currently split into two distinct areas: the customizer controls “pane” and the customize preview. The preview is currently in an iframe, meaning that all JS runs either in the controls pane or in the preview. The postMessage API is used to communicate between the preview and the controls.
Most themes only implement JavaScript in the customize preview, and use it to implement instant previewing of settings via postMessage. However, JS on the controls side can be used for many things, such as dynamically showing and hiding controls based on the values of other settings, changing the previewed URL, focusing parts of the preview, and more. Here’s an example from core of controls-side JS that interacts with the preview, in this case changing the previewed URL when the page for posts changes:
// Change the previewed URL to the selected page when changing the page_for_posts.
wp.customize(
	'page_for_posts',
	function( setting ) {
		setting.bind( function( pageId ) {
			pageId = parseInt( pageId, 10 );
			if ( pageId > 0 ) {
				api.previewer.previewUrl.set( api.settings.url.home + '?page_id=' + pageId );
			}
		});
	}
);
Similar logic can be used to 
activate UI objects based on the value of a setting. The Twenty Seventeen theme includes some useful examples for leveraging the customize JS API for improved user experience. Note that there is one JS file for the controls pane, named 
customize-controls.js and one file for the customize preview, named customize-preview.js. For clarity, all themes and plugins are recommended to follow this naming convention, even if customize JS is only provided in the controls or preview but not both.
The rest of this page is dedicated primarily to the controls-side JS API that was built-out in WordPress 4.1.
Models for Controls, Sections, and Panels
As in PHP, each Customizer object type has a corresponding object in JavaScript. There are 
wp.customize.Control, 
wp.customize.Panel, and 
wp.customize.Sectionmodels, as well as 
wp.customize.panel, 
wp.customize.section, and``wp.customize.control collections (yes, they are singular) that store all control instances. You can iterate over panels, sections, and controls via:
wp.customize.panel.each( function ( panel ) { /* ... */ } );
wp.customize.section.each( function ( section ) { /* ... */ } );
wp.customize.control.each( function ( control ) { /* ... */ } );
Relating Controls, Sections, and Panels together
When registering a new control in PHP, you pass in the parent section ID:
<?php
$wp_customize->add_control(
	'blogname',
	array(
		'label'   => __( 'Site Title' ),
		'section' => 'title_tagline',
	)
);
?>
In the JavaScript API, a control’s section can be obtained predictably:
id = wp.customize.control( 'blogname' ).section(); // returns title_tagline by default
To get the section object from the ID, look up the section by the ID as normal: 
wp.customize.section( id ).
You can move a control to another section using this 
section state as well, here moving it to the Navigation section:
wp.customize.control( 'blogname' ).section( 'nav' );
Likewise, you can get a section’s panel ID in the same way:
id = wp.customize.section( 'sidebar-widgets-sidebar-1' ).panel(); // returns widgets by default
You can go the other way as well, to get the children of panels and sections:
sections = wp.customize.panel( 'widgets' ).sections();controls = wp.customize.section( 'title_tagline' ).controls();
You can use these to move all controls from one section to another:
_.each( wp.customize.section( 'title_tagline' ).controls(), function ( control ) {  
    control.section( 'nav' );
} );
Contextual Panels, Sections, and Controls
Control, 
Panel, and 
Section instances have an 
active state (a 
wp.customize.Value instance). When the 
active state changes, the panel, section, and control instances invoke their respective 
onChangeActive method, which by default slides the container element up and down, if 
false and 
true respectively. There are also 
activate() and 
deactivate() methods now for manipulating this 
active state, for panels, sections, and controls. The primary purpose of these states is to show or hide the object without removing it entirely from the Customizer.
wp.customize.section( 'nav' ).deactivate(); // slide up
wp.customize.section( 'nav' ).activate({ duration: 1000 }); // slide down slowly
wp.customize.section( 'colors' ).deactivate({ duration: 0 }); // hide immediately
wp.customize.section( 'nav' ).deactivate({ completeCallback:
function () {  
    wp.customize.section( 'colors' ).activate(); // show after nav hides completely
} } );
Note that manually changing the 
active state would only stick until the preview refreshes or loads another URL. The 
activate()/
deactivate() methods are designed to follow the pattern of the new 
expanded state.
Focusing UI Objects
Building upon the 
expand()/
collapse() methods for panels, sections, and controls, these models also support a 
focus() method which not only expands all of the necessary elements, but also scrolls the target container into view and puts the browser focus on the first focusable element in the container. For instance, to expand the “Static Front Page” section and focus on select dropdown for the “Front page”:
wp.customize.control( 'page_on_front' ).focus()
The focus functionality is used to implement autofocus: deep-linking to panels, sections, and controls inside of the customizer. Consider these URLs:
…/wp-admin/customize.php?autofocus[panel]=widgets
…/wp-admin/customize.php?autofocus[section]=colors
…/wp-admin/customize.php?autofocus[control]=blogname
This is used in WordPress core to add a link on the widgets admin page to link directly to the widgets panel within the customizer, as well as to connect visible edit shortcuts in the customize preview with the associated controls in the customize pane.
Priorities
When registering a panel, section, or control in PHP, you can supply a 
priority parameter. This value is stored in a 
wp.customize.Value instance for each respective 
Panel, 
Section, and 
Control instance. For example, you can obtain the priority for the widgets panel via:
priority = wp.customize.panel( 'widgets' ).priority(); // returns 110 by default
You can then dynamically change the priority and the Customizer UI will automatically re-arrange to reflect the new priorities:
wp.customize.panel( 'widgets' ).priority( 1 ); // move Widgets to the top
Custom Controls, Panels, and Sections
When working with custom Customizer objects in JS, it is usually easiest to examine the custom objects in WordPress core to understand the code structure. See wp-admin/js/customize-controls.js, particularly the wp.customize.Panel|Section|Control models. Note several examples in the core code, particularly in the media controls, which build on each others’ functionality though object hierarchy.

Tools for Improved User Experience
Contextual Controls, Sections, and Panels
WordPress 4.0 and 4.1 also added support for making parts of the Customizer UI be visible or hidden depending on the part of the site that the user was previewing within the Customizer preview window. A simple contextual control example would be that your theme only displays the header image and the site tagline on the front page. This is a perfect use case for the Customizer Manager’s get_ methods, as we can modify the core controls for these settings directly to make them contextual to the front page:
// Hide core sections/controls when they aren't used on the current page.
$wp_customize->get_section( 'header_image' )->active_callback = 'is_front_page';
$wp_customize->get_control( 'blogdescription' )->active_callback = 'is_front_page';
In this contextual control example, the theme only displays the site tagline on the front page, so the corresponding field in the Customizer is hidden when the user navigates to a different page within the preview window.
The 
active_callback parameter for Panels, Sections, and Controls takes a callback function name, either core or custom. This parameter can also be set when registering the object for objects that you add. Here’s an example from the Twenty Fourteen Theme:
$wp_customize->add_section( 'featured_content', array(
  'title'       => __( 'Featured Content', 'twentyfourteen' ),
  'description' => //...
  'priority'        => 130,
  'active_callback' => 'is_front_page',
) );
In the previous example, 
is_front_page is used directly. But for more complex logic, such as checking if the current view is a page (or even a specific page, by id), custom functions can be used (see #30251 for details on why this is needed). If you don’t need to support PHP 5.2, this can be done inline:
'active_callback' => function () { return is_page(); }
PHP 5.2 support is as simple as creating a named function and referencing it with the active_callback parameter:
//...
'active_callback' => 'prefix_return_is_page';
//...
function prefix_return_is_page() {
  return is_page();
}
Within Custom Controls, Sections, and Panels, there is also an option to override the 
active_callback function directly within the custom Customizer object class:
class WP_Customize_Greeting_Control extends WP_Customize_Control {
  // ...
  function active_callback() {
    return is_front_page();
  }
}
Finally, there is a filter that can be used to override all other 
active_callback behavior:
// Hide all controls without a description when previewing single posts.
function title_tagline_control_filter( $active, $control ) {
  if ( '' === $control->description ) {
    $active = is_singular();
  }
  return $active;
}
add_filter( 'customize_control_active', 'title_tagline_control_filter', 10, 2 );
Note that the 
active_callback API works exactly the same for all of the Customizer object types (Controls, Sections, and Panels). As an added bonus, sections will automatically be hidden if all of the controls within them are contextually hidden, and the same works for panels.
Selective Refresh: Fast, Accurate Updates
Introduced in WordPress 4.5, Selective Refresh updates in the Customizer “preview” only refresh areas whose associate settings are changed. By only updating the elements that have changed, it’s much faster and less disruptive than a full-iframe refresh. Some other benefits, as noted in Selective Refresh In The Customizer, are:
Don’t Repeat Yourself (DRY) logic
Accurate preview update
Association between parts of the preview and associated settings and controls, along with visible edit shortcuts as of WordPress 4.7
The logic in pure-JavaScript 
postMessage updates is duplicated. The JavaScript in the Customizer must mirror the PHP that produces the markup, or take shortcuts to approximate it. But Selective Refresh is DRY as there’s no duplication of JavaScript and PHP. An Ajax request retrieves the new markup for the preview.
And because of this Ajax call, the refresh is accurate. It uses the filters that can alter the markup. It shows the same result that appears on the front end.
Additionally, selective refresh partials provide an association between areas of the preview and their corresponding settings. The customizer leverages this relationship to provide visible edit shortcuts that help users find controls associated with a particular part of their site. In the future the partials API could expand to facilitate editing settings directly within the preview and to include a structured JS API for previewing settings with partials.
For these reasons, all settings are strongly recommended to leverage selective refresh transport for improved user experience, with the option of providing additional JavaScript-based transport to further enhance setting previewing.
Registering Partials
Setting previews need to opt-in to use Selective Refresh by registering the necessary partials. In this example, largely taken from the them Twenty Sixteen, Selective Refresh is added for the 
blogdescription setting by adding a partial with the same name.
function foo_theme_customize_register( WP_Customize_Manager $wp_customize ) {
    $wp_customize->selective_refresh->add_partial( 'blogdescription', array(
        'selector' => '.site-description',
        'container_inclusive' => false,
        'render_callback' => function() {
            bloginfo( 'description' );
        },
    ) );
}
add_action( 'customize_register', 'foo_theme_customize_register' );
If the 
settings argument is not supplied, it defaults to be the same as the partial ID, in the same way as the settings for controls default to the control ID. Here are some of the key arguments for partials:
Variable
Type
Description
settings
array
Setting IDs associated with the partial.
selector
string
Targets the element(s) in the page markup to be refreshed.
container_inclusive
boolean
If true, a refresh replaces the entire container. Otherwise, it only replaces the container’s children. Defaults to false.
render_callback
function
Produces the markup to be rendered on refresh.
fallback_refresh
bool
Whether or not a full page refresh should occur if the partial is not found in the document.
Selective Refresh JavaScript Events
These fire on 
wp.customize.selectiveRefresh:
partial-content-rendered
When the placement is rendered. As mentioned, JavaScript-driven widgets can re-build on this event.
render-partials-response
When data is returned, after a request for partial rendering. The server filters this data with ‘customize_render_partials_response’.
partial-content-moved
When a widget has moved in its sidebar. As shown above, JavaScript-driven widgets can refresh on this event.
widget-updated
When the 
WidgetPartial is refreshed with its 
renderContent method.
sidebar-updated
When a sidebar has a widget that’s refreshed or updated. Or when a sidebar’s widgets are sorted, using 
reflowWidgets().
Widgets: Opting-In To Selective Refresh
Both themes and widgets need to opt-in to use Selective Refresh. All core widgets and themes have already enabled this.
Theme Support In Sidebars
In order to allow partial refreshes of widgets in a theme’s sidebars:
add_theme_support( 'customize-selective-refresh-widgets' );
Important: Selective refresh for widgets requires that the theme include a 
before_widget/
after_widget wrapper element around each widget that contains the widget’s ID. Such wrappers are the default when you 
register_sidebar(). For example:
function example_widgets_init() {
	register_sidebar(
		array(
			'name'          => esc_html__( 'Sidebar', 'example' ),
			'id'            => 'sidebar-1',
			'description'   => esc_html__( 'Add widgets here.', 'example' ),
			'before_widget' => '<section id="%1$s" class="widget %2$s">', // <= Key for selective refresh.
			'after_widget'  => '</section>',
			'before_title'  => '<h2 class="widget-title">',
			'after_title'   => '</h2>',
		)
	);
}
add_action( 'widgets_init', 'example_widgets_init' );
Widget Support
Even if a theme supports Selective Refresh, widgets also have to opt-in. All core widgets have already enabled it. Here’s an example widget adding support for Selective Refresh:
class Foo_Widget extends WP_Widget {
    public function __construct() {
        parent::__construct(
            ‘foo’,
            __( 'Example', 'bar-plugin' ),
            array(
                'description' => __( ‘An example widget’, ‘bar-plugin’ ),
                'customize_selective_refresh' => true,
            )
        );
        if ( is_active_widget( false, false, $this->id_base ) || is_customize_preview() ) {
            add_action( 'wp_enqueue_scripts', array( $this, 'enqueue_scripts' ) );
        }
    }
    ...
Line 9 above enables Selective Refresh:
'customize_selective_refresh' => true,
Line 13 above ensures the widget’s stylesheet always appears in Customizer sessions. Adding the widget won’t cause a full-page refresh to retrieve the styling:
if ( is_active_widget( false, false, $this->id_base ) || is_customize_preview() ) {
    add_action( 'wp_enqueue_scripts', array( $this, 'enqueue_scripts' ) );
}
See Implementing Selective Refresh Support for Widgets.
JavaScript-Driven Widget Support
Widgets that rely on JavaScript for their markup will need additional steps, as shown in Implementing Selective Refresh Support for Widgets:
Enqueue any JavaScript files based on 
is_customize_preview(), as shown above for stylesheets.
Add a handler for the 
partial-content-rendered event, and refresh the widget as needed:
wp.customize.selectiveRefresh.bind( 'partial-content-rendered', function( placement ) {
    // logic to refresh
} );
If the widget includes an iframe, add a handler to refresh the partial:
wp.customize.selectiveRefresh.bind( 'partial-content-moved', function( placement ) {
    // logic to refresh, perhaps conditionally
}
Using PostMessage For Improved Setting Previewing
The Customizer automatically handles previewing all settings out-of-the-box. This is done by silently reloading the entire preview window, with settings being filtered by PHP in that Ajax call. While this works just fine, it can be very slow since the entire front-end must be reloaded for every single setting change. Selective Refresh improves this experience by refreshing only the elements that have changed, but due to the Ajax call, there is still a delay in seeing the changes in the preview.
To further improve the user experience, the Customizer offers an API for managing setting changes directly in JavaScript, allowing for truly-live previewing. The below images show a comparison of a Custom CSS option that leverages this technology, called 
postMessage, versus the standard refresh option:
Custom CSS setting in the Customizer with the postMessage setting transport.
Custom CSS setting in the Customizer with the default refresh setting transport.
To use postMessage, first set the transport parameter to postMessage when adding your setting. Many themes also modify core settings such as the title and tagline to leverage postMessage by modifying the transport property of those settings:
$wp_customize->get_setting( 'blogname' )->transport        = 'postMessage';
$wp_customize->get_setting( 'blogdescription' )->transport = 'postMessage';
Once the setting’s transport is set to postMessage, the setting will no longer trigger a refresh of the preview when its value changes. To implement the JavaScript to update the setting within the preview of the front-end, first create and enqueue a JavaScript file:
function my_preview_js() {
  wp_enqueue_script( 'custom_css_preview', 'path/to/file.js', array( 'customize-preview', 'jquery' ) );
}
add_action( 'customize_preview_init', 'my_preview_js' );
Your JavaScript file should look something like this:
( function( $ ) {
  wp.customize( 'setting_id', function( value ) {
    value.bind( function( to ) {
      $( '#custom-theme-css' ).html( to );
    } );
  } );
  wp.customize( 'custom_plugin_css', function( value ) {
    value.bind( function( to ) {
      $( '#custom-plugin-css' ).html( to );
    } );
  } );
} )( jQuery );
Note that you don’t necessarily need to be great with JavaScript to use postMessage – most of the code is boilerplate. The types of settings that benefit most from postMessage transport require simple JS changes such as using jQuery’s .html() or .text() methods, or swapping out a class on the 
<body> or another element to trigger a different set of CSS rules. Doing this, or simplifying the instant preview logic with fully-accurate changes updating with selective refresh, the user experience can be fast without duplicating all of the PHP logic in JS.
Setting Validation
WordPress 4.6 includes new APIs related to validation of Customizer setting values. The Customizer has had sanitization of setting values since it was introduced. Sanitization involves coercing a value into something safe to persist to the database: common examples are converting a value into an integer or stripping tags from some text input. As such, sanitization is a lossy operation. With the addition of setting validation:
All modified settings are validated up-front before any of them are saved.
If any setting is invalid, the Customizer save request is rejected: a save thus becomes transactional with all the settings left dirty to try saving again. (The Customizer transactions proposal is closely related to setting validation here.)
Validation error messages are displayed to the user, prompting them to fix their mistake and try again.
Sanitization and validation are also both part of the REST API infrastructure via 
WP_REST_Request::sanitize_params() and 
WP_REST_Request::validate_params(), respectively. A setting’s value goes through validation before it goes through sanitization.
For more information on the validation behavior, and additional code examples, see the feature announcement post.
Validating Settings in PHP
Just as you can supply a 
sanitize_callback when registering a setting, you can also supply a 
validate_callback arg:
$wp_customize->add_setting( 'established_year', array(
    'sanitize_callback' => 'absint',
    'validate_callback' => 'validate_established_year'
) );
function validate_established_year( $validity, $value ) {
    $value = intval( $value );
    if ( empty( $value ) || ! is_numeric( $value ) ) {
        $validity->add( 'required', __( 'You must supply a valid year.' ) );
    } elseif ( $value &lt; 1900 ) {
        $validity->add( 'year_too_small', __( 'Year is too old.' ) );
    } elseif ( $value > gmdate( 'Y' ) ) {
        $validity->add( 'year_too_big', __( 'Year is too new.' ) );
    }
    return $validity;
}
Just as supplying a 
sanitize_callback arg adds a filter for 
customize_sanitize_{$setting_id}, so too supplying a 
validate_callback arg will add a filter for 
customize_validate_{$setting_id}. Assuming that the 
WP_Customize_Setting instances apply filters on these in their 
validate methods, you can add this filter if you need to add validation for settings that have been previously added.
The 
validate_callback and any 
customize_validate_{$setting_id} filter callbacks take a 
WP_Error instance is its first argument (which initially is empty of any errors added), followed by the 
$value being sanitized, and lastly the 
WP_Customize_Setting instance that is being validated.
Custom setting classes can also override the 
validate method of the setting class directly.
Client-side Validation
If you have a setting that is previewed purely via JavaScript (and the 
postMessage transport without selective refresh), you should also add client-side validation. Otherwise, any validation errors will persist until a full refresh happens or a save is attempted. Client-side validation must not take the place of server-side validation, since malicious users could bypass the client-side validation to save an invalid value if corresponding server-side validation is not in place.
There is a 
validate method available on the 
wp.customize.Setting JS class (actually, the 
wp.customize.Value base class). Its name is a bit misleading, as it actually behaves very similarly to the 
WP_Customize_Setting::sanitize() PHP method, but it can be used to both sanitize and validate a value in JS. Note that this JS runs in the context of the Customizer pane not the preview, so any such JS should have 
customize-controls as a dependency (not 
customize-preview) and enqueued during the 
customize_controls_enqueue_scripts action. Some example JS validation:
wp.customize( 'established_year', function ( setting ) {
	setting.validate = function ( value ) {
		var code, notification;
		var year = parseInt( value, 10 );
		code = 'required';
		if ( isNaN( year ) ) {
			notification = new wp.customize.Notification( code, {message: myPlugin.l10n.yearRequired} );
			setting.notifications.add( code, notification );
		} else {
			setting.notifications.remove( code );
		}
		code = 'year_too_small';
		if ( year &lt; 1900 ) {
			notification = new wp.customize.Notification( code, {message: myPlugin.l10n.yearTooSmall} );
			setting.notifications.add( code, notification );
		} else {
			setting.notifications.remove( code );
		}
		code = 'year_too_big';
		if ( year > new Date().getFullYear() ) {
			notification = new wp.customize.Notification( code, {message: myPlugin.l10n.yearTooBig} );
			setting.notifications.add( code, notification );
		} else {
			setting.notifications.remove( code );
		}
		return value;
	};
} );
Notifications
Notifications provide user feedback, typically based on the value of a control’s setting. An error notification is added to a setting’s 
notifications collection when a setting’s validation routine returns a 
WP_Error instance. Each error added to a PHP 
WP_Error instance is represented as a 
wp.customize.Notification in JavaScript:
A 
WP_Error‘s 
code is available as 
notification.code in JS.
A 
WP_Error‘s 
message is available as 
notification.message in JS. Note that if there are multiple messages added to a given error code in PHP they will be concatenated into a single message in JS.
A 
WP_Error‘s 
data is available as 
notification.data in JS. This is useful to pass additional error context from the server to the client.
Any time that a 
WP_Error is returned from a validation routine on the server it will result in a 
wp.customize.Notification being created with a 
type property of “error”.
While setting non-error notifications from PHP is not currently supported (see #37281), you can also add non-error notifications with JS as follows:
wp.customize( 'blogname', function( setting ) {
    setting.bind( function( value ) {
        var code = 'long_title';
        if ( value.length > 20 ) {
            setting.notifications.add( code, new wp.customize.Notification(
                code,
                {
                    type: 'warning',
                    message: 'This theme prefers title with max 20 chars.'
                }
            ) );
        } else {
            setting.notifications.remove( code );
        }
    } );
} );
You can also supply “info” as a notification’s 
type. The default 
type is “error”. Custom types may also be supplied, and the notifications can be styled with CSS selector matching 
notice.notice-foo where “foo” is the type supplied. A control may also override the default behavior for how notifications are rendered by overriding the 
wp.customize.Control.renderNotifications method.

404 Pages
A 404 page is important to add into your theme in case a user stumbles upon a page that doesn’t exist or hasn’t been created yet. It is also important that your 404 page gives your visitors a way to arrive at the right place.
These next few steps will help you build a useful 404 page for your WordPress theme.
Creating the 404.php file
As the 
404.php file is used on a page not found error, the first step is to create a file named 
404.php and add it to your WordPress theme folder.
Often times a great starting point for your 
404.php is your 
index.php
Add a file header
To use your theme’s 
header.php file, open your 
404.php file. At the top, add a comment describing what the file is and make sure you include your theme’s header.
For example:
/**
 * The template for displaying 404 pages (Not Found)
 */
get_header();
Adding the body to your 404 Page
To make the 404 page functional you have to add the body content to your template:
Example:
<div id="primary" class="content-area">
		<div id="content" class="site-content" role="main">
			<header class="page-header">
				<h1 class="page-title"><?php _e( 'Not Found', 'twentythirteen' ); ?></h1>
			</header>
			<div class="page-wrapper">
				<div class="page-content">
					<h2><?php _e( 'This is somewhat embarrassing, isn’t it?', 'twentythirteen' ); ?></h2>
					<p><?php _e( 'It looks like nothing was found at this location. Maybe try a search?', 'twentythirteen' ); ?></p>
					<?php get_search_form(); ?>
				</div><!-- .page-content -->
			</div><!-- .page-wrapper -->
		</div><!-- #content -->
	</div><!-- #primary -->
This example is from the Twenty Thirteen theme that comes with WordPress. This adds some text and a search form in the 404 page.
You can to add your own text to make your 404 page look better.
Adding the footer and sidebar.
The final step when creating a 404 page is to add the footer. You may also add a sidebar if you want.
Example:
get_sidebar();
get_footer();
Now you have a functional 404 page with a search form and some text in case a user stumbles upon the wrong page. Once you make sure the 
404.php has been uploaded, you can test your 404 page. Just type a URL address for your website that doesn’t exist. You can try something like 
http://example.com/fred.php. This is sure to result in a 404 error unless you actually have a PHP file called 
fred.php.

Accessibility
A WordPress theme should generate pages everyone can use, including those who cannot see or use a mouse.
To create an accessible theme, you need to have knowledge of web standards for HTML, CSS, and JavaScript.
You also need to be aware of best practices for web accessibility and have basic knowledge of the Web Content Accessibility Guidelines, WCAG.
To succeed in making your theme accessible, accessibility should be considered from the start of your project as part of your project specification. By making the right decisions from the beginning, you can avoid making last-minute adjustments that can be costly, time-consuming, and of low quality.
The Accessibility Team have documented many of the best practices and resources for development, design, and content in their handbook. In the handbook, you can also learn about testing for accessibility.
The Themes Team has two sets of accessibility requirements for themes submitted to the WordPress.org theme directory:
Requirements for all themes
Requirements for using the “‘accessibility-ready” tag
The accessibility-ready requirements are based on WCAG but adapted for WordPress themes.
“Accessibility Ready” does not mean that the theme meets the WCAG guidelines AA-level. It means that the theme reaches the minimum standards that the theme review team has set.
The four principles of web accessibility
Although web accessibility can be a complex subject, it boils down to only four principles. The content must be:
Perceivable
Content must be available to all. It should not depend on a specific device or browser or require a specific physical sense, such as sight or sound.
Operable
Users must be able to move around and operate the final site effectively, whether they’re using a keyboard, a mouse, or assistive technology.
Understandable
The content should be presented in a manner that supports understanding, including supporting the construction of a mental model of the site for screen reader users. Similarly, the site’s operation (navigation menus, links, forms, etc.) should be easily understandable. Building a theme that incorporates known user behaviors (such as underlining links within the main content area) helps in this respect.
Robust
Content must be equally available across a wide range of user agents. Disabled users may employ a range of hardware and software solutions (commonly referred to as “assistive technology”) to allow them to access the Web—including screen reading & voice recognition software, braille readers, and switches (single input devices).
A theme designed with these four principles in mind eases the creation of an accessible website.
Perceivable and understandable
Color and color contrast
Having a high enough color contrast between background and foreground colors makes content easier to read. Theme authors must ensure that all background/foreground color contrasts for plain content text are within the level AA contrast ratio (4.5:1) specified in the Web Content Accessibility Guidelines (WCAG) 2.0 for color luminosity.
Color may not be the only way to identify controls, links in text content, or error messages.
If there is no text decoration on linked text, there must be a 3:1 color contrast between the link text color and the surrounding non-link text color, in addition to the other color contrast requirements.
There are separate requirements for links in content (links surrounded by other text) and links that are grouped together in navigation menus. Groups of links do not need to be underlined if it is obvious from the context that they are links.
Best practices for the use of color
Accessibility-ready requirements for contrast
Resizable text
Users have many means to resize text, including browser settings. All content and functionality must remain available if the user resizes the text up to 200% of the original size.
Resizing text must not trigger multi-dimensional scrolling
Enlarged texts must not cause overflows or overlaps
To avoid these issues, it is recommended to:
Use a relative unit for font sizes and line heights
Test your theme in different browsers and screen widths
Best practices for font sizes and resized text
Images
Non-decorative images
Example:
A header image that replaces header text
Images used in place of text for navigation
Non-decorative images included with 
img elements should have an 
alt attribute.
Decorative images
Example:
A header image used alongside header text
Images and icons accompanying navigation text links
When possible, decorative images should be included using CSS.
Decorative images included with 
img elements should have an empty 
alt attribute: 
alt="".
Decorative images that are displayed together with text should be hidden from screen readers using 
aria-hidden.
Featured images
The alt attribute for featured images is defined in the media library.
If the featured image is unlinked, the alt attribute should describe the image
If the featured image is linked to a post, the alt text should use the post title
Best practices for alt texts
Accessibility-ready requirement for images
Operable
Controls
All controls must be usable with the keyboard on all screen sizes, including but not limited to buttons for opening and closing menus, submenus, any type of dialog, modal, and popup.
Best practices for dialog modals
Accessibility-ready requirements for controls
Headings
Headings are an essential way of breaking content down into logical sub-sections. Heading levels indicate the importance of the content. Screen reader users can scan the contents of a page by reading the headings, and navigating to a section via its heading. That is why it is important that headings are used logically and not for presentational purposes.
Best practices for Heading structure in theme development
Accessibility-ready requirements for headings
Links
Link text
Link text should describe the resource that it links to, even when the text is read out of context. Some assistive software scans a page for links and presents them to the user as a simple list. In these situations, all the links will be read out of context. So it is important the text used in a link is descriptive. Bare URLs should never be used as links.
Good link texts
Accessibility-ready requirements: Avoiding repetitive Read More or Continue reading texts.
Link underlining and styling link states
Generally speaking, links should be underlined if they are outside navigation menus and lists. Using color alone to distinguish links is insufficient as not everyone can perceive color.
Users must be able to tell if a text is linked if they are hovering over a link, if they are focusing on a link, and if they have already visited a link. The default browser style for the focus state should not be removed unless replaced with a more visible focus style.
Accessibility-ready requirements for underlining links in the content
Skip Links
Skip links provide a mechanism that enables users to navigate directly to content or navigation on entering any given page. For example, a skip to content link might allow a user to skip a header area and go directly to the main content.
In designs with multiple menus and content areas, multiple skip links can be used:
Skip to the main navigation
Skip to content
Skip to footer
These links may be positioned off-screen initially using an appropriate CSS technique but should remain available to screen reader users and be visible on focus for sighted keyboard navigators.
Best practices for Skip Links
Accessibility-ready requirements for Skip Links
Forms
Provide enough information for the user to be able to complete the form.
All input fields must have a label. A placeholder text is not a replacement for the label. Input fields must also have a visible focus style.
Group controls that belong together, for example, a set of related checkboxes, with a 
fieldset and 
legend.
Make sure that the tab order in the form matches the visual order of the input fields: Do not move focus unexpectedly or skip past input fields.
On Form Submission
Post-submission responses—including any error messages—should always be perceivable. If possible, error messages should be generated at the top of the post-submission page so the user is immediately aware of any issues. Error messages should also make sense when read out of context.
Best practices for forms
Accessibility-ready requirements for forms
Robust
Use the HTML element that is the best match for the content. Use buttons when performing an action, and links when navigating to a part of a page or a new page.
The content of the website should be available even if the user disables both JavaScript and CSS
Establish which browsers your theme supports and test your theme with these browsers on different screen sizes
Resources
Make WordPress Accessible is the official blog for the WordPress Accessibility Team, dedicated to making WordPress accessible to as many people as possible. Anyone can join in the discussions, bug scrubs, and meetings. You can also follow discussions via email or subscribe to feeds for posts and comments.
Test for web accessibility
Development tools
WCAG 2 (external link)
Changelog:
Rewritten and published 2023-02-16

Administration Menus
This is no longer the recommended way to work with theme options. The Customizer API is the recommended way to give more control and flexibility to your users
Theme authors might need to provide a settings screen, so users can customize how their theme is used or works. The best way to do this is to create an administration menu item that allows the user to access that settings screen from all the administration screens.
Function Reference
Menu Pages
add_menu_page()
add_object_page()
add_utility_page()
remove_menu_page()
Sub-menu Pages
add_submenu_page()
remove_submenu_page()
WordPress Administration Menus
add_dashboard_page()
add_posts_page()
add_media_page()
add_links_page()
add_pages_page()
add_comments_page()
add_theme_page()
add_plugins_page()
add_users_page()
add_management_page()
add_options_page()
Every Plot Needs a Hook
To add an administration menu, there are three things you need to do:
Create a function that contains the menu-building code.
Register the above function using the 
admin_menu action hook – or 
network_admin_menu, if you are adding a menu for the Network.
Create the HTML output for the screen, displayed when the menu item is clicked.
Most developers overlook the second step in this list. You can’t simply call the menu code. You need to put it inside a function, and then register this function.
Here is a simple example of these three steps described. This will add a sub-level menu item under the Settings top-level menu. When selected, that menu item will show a very basic screen.
<?php
/** Step 2 (from text above). */
add_action( 'admin_menu', 'my_menu' );
/** Step 1. */
function my_menu() {
	add_options_page(
		'My Options',
		'My Menu',
		'manage_options',
		'my-unique-identifier',
		'my_options'
	);
}
/** Step 3. */
function my_options() {
	if ( ! current_user_can( 'manage_options' ) ) {
		wp_die( __( 'You do not have sufficient permissions to access this page.' ) );
	}
	echo 'Here is where I output the HTML for my screen.';
	echo '</div><pre>';
}
In this example, the function 
my_menu() adds a new item to the Settings administration menu via the 
add_options_page() function.
Note: Note that the add_action() call in Step 2 registers the my_menu() function under the admin_menu hook. Without that, add_action() call, a PHP error for undefined function will be thrown. Finally, the 
add_options_page() call refers to the 
my_options() function which contains the actual page to be displayed (and PHP code to be processed) when someone clicks the menu item.
These steps are described in more detail in the sections below. Remember to enclose the creation of the menu and the page in functions, and use the 
admin_menu hook to get the whole process started at the right time.
Determining Location for New Menus
Before creating a new menu, first decide if the menu should be a top-level menu, or a sub-level menu item. A top-level menu displays as new section in the administration menus and contains sub-level menu items. This means a sub-level menu item is a member of an existing top-level menu.
It is rare that a theme would require the creation of a new top-level menu. If the theme introduces an entirely new concept to WordPress and needs many screens to do it, then that theme may warrant a new top-level menu. Adding a top-level menu should only be considered if you really need multiple, related screens to make WordPress do something it was not originally designed to accomplish. Examples of new top-level menus might include job management or conference management. Please note that, with the native post type registration, WordPress automatically creates top-level menus to manage this kind of features.
If the creation of a top-level menu is not necessary, you need to decide under what top-level menu to place your new sub-level menu item. As a point of reference, several themes add sub-level menu items underneath existing WordPress top-level menus.
Use this guide of the WordPress top-level menus to determine the correct location for your sub-level menu item:
Dashboard – information central for your site and include the Updates option for updating WordPress core, plugins, and themes.
Posts – displays tools for writing posts (time oriented content).
Media – uploading and managing your pictures, videos, and audio.
Links – manage references to other blogs and sites of interest.
Pages – displays tools for writing your static content called pages.
Comments – controlling and regulation reader to responses to posts.
Appearance – displays controls for manipulation of theme/style files, sidebars, etc.
Plugins – displays controls dealing with plugin management, not configuration options for a plugin itself.
Users – displays controls for user management.
Tools – manage the export, import, and even backup of blog data.
Settings – displays plugin options that only administrators should view.
Network Admin – displays plugin options that are set on the Network. Instead of 
admin_menu, you should use 
network_admin_menu (see also Create A Network)
Top-Level Menus
If you have decided your theme requires a brand-new top-level menu, the first thing you’ll need to do is to create one with the 
add_menu_page() function. Note: skip to Sub-Level Menus if you don’t need a top-level menu.
Parameter values:
page_title – the text to be displayed in the title tags of the page when the menu is selected.
menu_title – the on-screen name text for the menu.
capability – the capability required for this menu to be displayed to the user. When using the Settings API to handle your form, you should use 
manage_options here as the user won’t be able to save options without it. User levels are deprecated and should not be used here.
menu_slug – the slug name to refer to this menu by (should be unique for this menu). Prior to Version 3.0 this was called the file (or handle) parameter. If the function parameter is omitted, the 
menu_slug should be the PHP file that handles the display of the menu page content.
function – the function that displays the page content for the menu page.
icon_url – the URL to the icon to be used for this menu. This parameter is optional.
position – the position in the menu order this menu should appear. By default, if this parameter is omitted, the menu will appear at the bottom of the menu structure. To see the current menu positions, use 
print_r( $GLOBALS[ 'menu' ] ) after the menu has loaded.
Sub-Level Menus – once your top-level menu is defined, or you have chosen to use an existing WordPress top-level menu, you are ready to define one or more sub-level menu items using the 
add_submenu_page() function.
Sub-Level Menus
If you want your new menu item to be a sub-menu item, you can create it using the 
add_submenu_page() function instead.
Parameter values:
parent_slug – the slug name for the parent menu, or the file name of a standard WordPress admin file that supplies the top-level menu in which you want to insert your sub-menu, or your plugin file if this sub-menu is going into a custom top-level menu. Examples:
Dashboard – 
add_submenu_page('index.php', ...)
Posts – 
add_submenu_page('edit.php', ...)
Media – 
add_submenu_page('upload.php', ...)
Links – 
add_submenu_page('link-manager.php', ...)
Pages – 
add_submenu_page('edit.php?post_type=page', ...)
Comments – 
add_submenu_page('edit-comments.php', ...)
Custom Post Types – 
add_submenu_page('edit.php?post_type=your_post_type', ...)
Appearance – 
add_submenu_page('themes.php', ...)
Plugins – 
add_submenu_page('plugins.php', ...)
Users – 
add_submenu_page('users.php', ...)
Tools – 
add_submenu_page('tools.php', ...)
Settings – 
add_submenu_page('options-general.php', ...)
page_title – text that will go into the HTML page title for the page when the submenu is active.
menu_title – the text to be displayed in the title tags of the page when the menu is selected.
capability – the capability required for this menu to be displayed to the user. User levels are deprecated and should not be used here.
menu_slug – for existing WordPress menus, the PHP file that handles the display of the menu page content. For sub-menus of a custom top-level menu, a unique identifier for this sub-menu page.
function – the function that displays the page content for the menu page. Technically, as in the 
add_menu_page function, the function parameter is optional, but if it is not supplied, then WordPress will basically assume that including the PHP file will generate the administration screen, without calling a function.
Using Wrapper Functions
Since most sub-level menus belong under the Settings, Tools, or Appearance menus, WordPress supplies wrapper functions that make adding a sub-level menu items to these top-level menus easier. Note that the function names may not match the names seen in the admin UI as they have changed over time:
Dashboard
<?php
add_dashboard_page(
	$page_title,
	$menu_title,
	$capability,
	$menu_slug,
	$function
);
Posts
<?php
add_posts_page(
	$page_title,
	$menu_title,
	$capability,
	$menu_slug,
	$function
);
Media
<?php
add_media_page(
	$page_title,
	$menu_title,
	$capability,
	$menu_slug,
	$function
);
Links
<?php
add_links_page(
	$page_title,
	$menu_title,
	$capability,
	$menu_slug,
	$function
);
Pages
<?php
add_pages_page(
	$page_title,
	$menu_title,
	$capability,
	$menu_slug,
	$function
);
Comments
add_comments_page(
	$page_title,
	$menu_title,
	$capability,
	$menu_slug,
	$function
);
Appearance
<?php
add_theme_page(
	$page_title,
	$menu_title,
	$capability,
	$menu_slug,
	$function
);
Plugins
<?php
add_plugins_page(
	$page_title,
	$menu_title,
	$capability,
	$menu_slug,
	$function
);
Users
<?php
add_users_page(
	$page_title,
	$menu_title,
	$capability,
	$menu_slug,
	$function
);
Tools
<?php
add_management_page(
	$page_title,
	$menu_title,
	$capability,
	$menu_slug,
	$function
);
Settings
<?php
add_options_page(
	$page_title,
	$menu_title,
	$capability,
	$menu_slug,
	$function
);
Also see Theme Options for the currently recommended way of creating options via the Customizer API.
Example
Here’s a quick example illustrating how to insert a top-level menu page and a sub-menu page, where the title on the sub-menu page is different from the top-level page. In this example, 
register_my_theme_more_settings_menu is the name of the function that displays the first sub-menu page:
<?php
function register_my_theme_settings_menu() {
	add_menu_page(
		"My Theme's Settings",
		'My Theme',
		'manage_options',
		'my-theme-settings-menu'
	);
}
function register_my_theme_more_settings_menu() {
	add_submenu_page(
		'my-theme-settings-menu',
		'More Settings for My Theme',
		'More Settings',
		'manage_options',
		'my-theme-more-settings-menu'
	);
}
add_action( 'admin_menu', 'register_my_theme_settings_menu' );
add_action( 'admin_menu', 'register_my_theme_more_settings_menu' );
Here’s an example of adding an option page under a custom post type menu block (see also here):
CODE
Inserting the Pages
Here is an example of how to insert multiple menus into various places:
<?php
// Hook for adding admin menus
add_action( 'admin_menu', 'mt_add_pages' );
// Action function for hook above
function mt_add_pages() {
	// Add a new submenu under Settings:
	add_options_page( __( 'Test Settings', 'menu-test' ), __( 'Test Settings', 'menu-test' ), 'manage_options', 'testsettings', 'mt_settings_page' );
	// Add a new submenu under Tools:
	add_management_page( __( 'Test Tools', 'menu-test' ), __( 'Test Tools', 'menu-test' ), 'manage_options', 'testtools', 'mt_tools_page' );
	// Add a new top-level menu (ill-advised):
	add_menu_page( __( 'Test Toplevel', 'menu-test' ), __( 'Test Top-level', 'menu-test' ), 'manage_options', 'mt-top-level-handle', 'mt_toplevel_page' );
	// Add a submenu to the custom top-level menu:
	add_submenu_page( 'mt-top-level-handle', __( 'Test Sub-Level', 'menu-test' ), __( 'Test Sub-Level', 'menu-test' ), 'manage_options', 'sub-page', 'mt_sublevel_page' );
	// Add a second submenu to the custom top-level menu:
	add_submenu_page( 'mt-top-level-handle', __( 'Test Sub-Level 2', 'menu-test' ), __( 'Test Sub-Level 2', 'menu-test' ), 'manage_options', 'sub-page2', 'mt_sublevel_page2' );
}
// mt_settings_page() displays the page content for the Test settings sub-menu.
function mt_settings_page() {
	echo '</pre><h2>' . __( 'Test Settings', 'menu-test' ) . '</h2><pre>';
}
// mt_tools_page() displays the page content for the Test Tools sub-menu.
function mt_tools_page() {
	echo '</pre><h2>' . __( 'Test Tools', 'menu-test' ) . '</h2><pre>';
}
// mt_toplevel_page() displays the page content for the custom Test Top-Level menu.
function mt_toplevel_page() {
	echo '</pre><h2>' . __( 'Test Top-Level', 'menu-test' ) . '</h2><pre>';
}
// mt_sublevel_page() displays the page content for the first sub-menu of the custom Test Toplevel menu.
function mt_sublevel_page() {
	echo '</pre><h2>' . __( 'Test Sub-Level', 'menu-test' ) . '</h2><pre>';
}
// mt_sublevel_page2() displays the page content for the second sub-menu of the custom Test Top-Level menu.
function mt_sublevel_page2() {
	echo '</pre><h2>' . __( 'Test Sub-Level 2', 'menu-test' ) . '</h2><pre>';
}
Sample Menu Page
Note: See the Settings API for information on creating settings pages.
The previous example contains several dummy functions, such as 
mt_settings_page(), as placeholders for actual page content. Let’s expand on them. What if you wanted to create an option called 
mt_favorite_color that allows the site owner to type in their favorite color via a Settings page? The 
mt_options_page() function will need to output a data entry form on the screen, as well as to process the entered data.
Here is a function that does this:
<?php
// mt_settings_page() displays the page content for the Test settings sub-menu.
function mt_settings_page() {
	// Must check that the user has the required capability.
	if ( ! current_user_can( 'manage_options' ) ) {
		wp_die( __( 'You do not have sufficient permissions to access this page.' ) );
	}
	// Variables for the field and option names
	$opt_name          = 'mt_favorite_color';
	$hidden_field_name = 'mt_submit_hidden';
	$data_field_name   = 'mt_favorite_color';
	// Read in existing option value from database
	$opt_val = get_option( $opt_name );
	// See if the user has posted us some information. If they did, this hidden field will be set to 'Y'.
	if ( isset( $_POST[ $hidden_field_name ] ) && $_POST[ $hidden_field_name ] == 'Y' ) {
		// Read their posted value.
		$opt_val = $_POST[ $data_field_name ];
		// Save the posted value in the database.
		update_option( $opt_name, $opt_val );
		// Put a "Settings updated" message on the screen
		?>
		<div class="updated"></div><!-- .updated -->
		<div class="wrap">
			<?php echo '<h2>' . __( 'Menu Test Settings', 'menu-test' ) . '</h2>'; ?>
			<form action="" method="post" name="form1"></form>
			<?php _e( 'Favorite Color:', 'menu-test' ); ?>
			<hr />
		</div><!-- .wrap -->
		<?php
	}
}
A few notes:
The WordPress functions such as 
add_menu_page() and 
add_submenu_page() take a capability which will be used to determine whether the top-level or sub-level menu is displayed.
The function which is hooked in to handle the output of the page must check that the user has the required capability as well.
The WordPress administration functions take care of validating the user login, so you don’t have to worry about it in your function.
The function example above has been internationalized — see the I18n for WordPress Developers for more details.
The function processes any entered data before putting the data entry form on the screen, so that the new values will be shown in the form (rather than the values from the database).
You don’t have to worry about this working the first time, because the WordPress 
update_option function will automatically add an option to the database if it doesn’t already exist.
These admin-menu-adding procedures are parsed every single time you navigate to a page in Admin. So if you are writing a theme which has no options page, but add one later, you can just add it using the instructions above and re-upload, and tweak until you’re happy with it. In other words, menus are not “permanently added” or put into a database upon activating a theme. They’re parsed on the fly, so you can add or subtract menu items at will, re-upload, and the change will be reflected right away.
Page Hook Suffix
Every function that adds a new administration menu – 
add_menu_page(), 
add_submenu_page() and its specialized versions such as 
add_options_page() – returns a special value called Page Hook Suffix. It can be used later as a hook to which an action called only on that particular page can be registered.
One such action hook is 
load-{page_hook}, where 
{page_hook} is the value returned by one of these 
add_*_page() functions. This hook is called when the particular page is loaded. In the example below, it is used to display the “Theme is not configured” notice on all admin pages except for plugin’s options page:
<?php
add_action( 'admin_menu', 'my_menu' );
// Here you can check if plugin is configured (e.g. check if some option is set). If not, add new hook.
// In this example hook is always added.
add_action( 'admin_notices', 'my_admin_notices' );
function my_menu() {
	// Add the new admin menu and page and save the returned hook suffix
	$hook_suffix = add_options_page( 'My Options', 'My Theme', 'manage_options', 'my-unique-identifier', 'my_options' );
	// Use the hook suffix to compose the hook and register an action executed when plugin's options page is loaded
	add_action( 'load-' . $hook_suffix, 'my_load_function' );
}
function my_load_function() {
	// Current admin page is the options page for our plugin, so do not display the notice
	// (remove the action responsible for this)
	remove_action( 'admin_notices', 'my_admin_notices' );
}
function my_admin_notices() {
	echo '<pre><div class="updated fade" id="notice">My Plugin is not configured yet. Please do it now.</div></pre>';
}
function my_options() {
	if ( ! current_user_can( 'manage_options' ) ) {
		wp_die( __( 'You do not have sufficient permissions to access this page.' ) );
	}
	echo '</pre><div class="wrap">';
	echo 'Here is where the form would go if I actually had options.';
	echo '</div><pre>';
}
Resources
Top Level Menu discussion on wp-hackersAdmin Menu Editor Plugin

Block theme accessibility
Block themes support accessibility and simplify the process for adding accessibility.
Landmark
Group, Template part, and Query blocks can become a landmark. There are two ways to create landmark.
Using block markup
”tagName":"header” creates header landmark.
<!-- wp:group {"tagName":"header","layout":{"type":"constrained"}} -->
<header class="wp-block-group"><!-- wp:site-title /--></header>
<!-- /wp:group -->
Using site editor
HTML element under Advanced section in the Block panel provides the following landmark options.
HTML element under Advanced section in the Block panel provides the following landmark options.
<header> 
<main> 
<section> 
<article> 
<aside> 
<footer>.
Skip to content
By selecting 
<main> landmark on Group, Template part, or Query block generates the Skip to Content link. Learn more about the skip to content link here.
<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
<main class="wp-block-group"><!-- wp:heading -->
<h2 id="hello-world">Hello World</h2>
<p>Welcome to WordPress. This is your first post. </p>
<!-- /wp:heading -->
Accessible navigation menu
Navigation block enables the following accessibility without additional code.
Support responsive view
Support keyboard navigation
Insert 
<nav> landmark role
Insert ARIA attributes 
aria-label 
aria-hidden
Additional resources
Accessibility
Changelog:
Updated 2023-03-08 Updated code examples to reflect WordPress 6.1 block markup.
Created 2022-01-25

Core-Supported Features
This page will list and somewhat detail all core-supported features. Each feature will have its own page.

Custom Backgrounds
Custom Backgrounds is a theme feature that provides for customization of the background color and image.
Theme developer needs 2 steps to implement it.
Enable Custom Background – add_theme_support()
Display Custom Background – wp_head() and body_class()
Enable Custom Backgrounds
Use add_theme_support() in the 
functions.php file to enable custom backgrounds.
add_theme_support( 'custom-background' );
You can specify default parameters. In below example using default ‘#0000ff’ background color (blue) with ‘wapuu.jpg’ background image that was stored under the /images folder.
$args = array(
    'default-color' => '0000ff',
    'default-image' => get_template_directory_uri() . '/images/wapuu.jpg',
);
add_theme_support( 'custom-background', $args );
By calling add_theme_support() , Customizer displays ‘Background Image’ menu and ‘Background Color’ section in Colors menu.
Display Custom Backgrounds
In general, invokes wp_head() and body_class() in 
header.php file to display the custom backgrounds.
<!DOCTYPE html>
<html>
<head>
    <?php wp_head(); ?>
</head>
<body <?php body_class(); ?>>
wp_head() generates an extra style sheet in-line with the HTML headers, usually right before the end of the document’s HEAD element. The extra style sheet overrides the background values from the theme’s style sheet.
In our example, following code will be generated in the HTML. Notice that body tag includes “custom-background ” class.
<!DOCTYPE html>
<html lang="en-US" class="no-js">
<head>
	...
<style type="text/css" id="custom-background-css">
body.custom-background {
  background-image: url("http://example.com/wordpress/wp-content/themes/my-first-theme/images/wapuu.jpg");
  background-position: left top;
  background-size: auto;
  background-repeat: repeat;
  background-attachment: scroll;
}
</style>
	...
</head>
<body class="home page-template-default page page-id-211 logged-in admin-bar no-customize-support custom-background">
	...
Now you’ll see repeated background images
Another default example
This is another example of default value set.
$another_args = array(
    'default-color'      => '0000ff',
    'default-image'      => get_template_directory_uri() . '/images/wapuu.jpg',
    'default-position-x' => 'right',
    'default-position-y' => 'top',
    'default-repeat'     => 'no-repeat',
);
add_theme_support( 'custom-background', $another_args );
This will show single image at the top right corner as below.
Even if we specified the ‘default-color’ as ‘#0000ff’ (blue), the background color is not blue. Setting the default-image parameter will instantly cause that value to become the effective Custom Background, whereas setting the default-color has no effect. It is just set as default background color in Color menu of Customizer, and enhanced when Administrator save it.

Custom Front Page Templates
By default, WordPress shows your most recent posts in reverse chronological order on the front page of your site. Many WordPress users want a static front page or splash page as the front page instead. This “static front page” look is common for users desiring static or welcoming information on the front page of the site.
The look and feel of the front page of the site is based upon the choices of the user combined with the features and options of the WordPress Theme.
Template Hierarchy of Custom Front Page
On the site front page, WordPress will always use the front-page.php template file, if it exists. If front-page.php does not exist, WordPress will determine which template file to use, depending on the user configuration of Settings > Reading >Front page displays, as follows:
A static page: WordPress uses the Static Page template hierarchy:
Custom Page Template
page-{id}.php
page-{slug}.php
page.php
index.php
Your latest posts: WordPress uses the Blog Posts Index template hierarchy:
home.php
index.php
Custom Site Front Page Template
To create a custom site front page template, include either of the following in the Theme:
front-page.php
A Custom Page Template (e.g. template-featured.php for featured content)
Custom Blog Posts Index Page Template
To create a custom blog posts index template, include the following in the Theme:
home.php
Use only the home.php template file for the blog posts index. Do not use a Custom Page Template (such as template-blog.php) for two reasons:
When the static front page feature is configured properly, WordPress will not use a Custom Page Template to display the blog posts index, even if a Custom Page Template is assigned to the page designated as the “Posts page”. WordPress will only use either home.php or index.php.
When the Custom Page Template is assigned to a static page other than the one designated as the “Posts page,” the blog posts index loop pagination will not work properly.
Contextual Conditional Tags
is_front_page
The Conditional Tag is_front_page() checks if the site front page is being displayed. Returns true when the site front page is being displayed, regardless of whether ‘Settings > Reading ->Front page displays’ is set to “Your latest posts” or “A static page”.
is_home
The Conditional Tag is_home() checks if the blog posts index is being displayed. Returns true when the blog posts index is being displayed: when the site front page is being displayed and ‘Settings > Reading ->Front page displays’ is set to “Your latest posts”, or when ‘Settings > Reading ->Front page displays’ is set to “A static page” and the “Posts Page” value is the current Page being displayed.
When the site front page is being displayed and ‘Settings > Reading ->Front page displays’ is set to “Your latest posts”, bothis_front_page()  and is_home()  will return true.
Configuration of front-page.php
If it exists, the front-page.php template file is used on the site’s front page regardless of whether ‘Settings > Reading ->Front page displays’ is set to “A static page” or “Your latest posts,” the Theme will need to account for both options, so that the site front page will display either a static page or the blog posts index. There are a few methods to do so.
Conditional display within front-page.php
One way to allow front-page.php to account for both options for ‘Settings > Reading ->Front page displays’ is to add a conditional inside of front-page.php itself, using get_option( 'show_on_front' ), get_home_template(), and get_page_template().
Method 1: including custom content directly within front-page.php:
if ( 'posts' == get_option( 'show_on_front' ) ) {
include( get_home_template() );
} else {
// Custom content markup goes here
}
Method 2: including any page template:
if ( 'posts' == get_option( 'show_on_front' ) ) {
include( get_home_template() );
} else {
include( get_page_template() );
}
Filtering frontpage_template
Another way to allow the site front page to display either a static page/custom content or the blog posts index, without adding conditional code within front-page.php, is to filter frontpage_template, by adding a filter callback to functions.php:
function themeslug_filter_front_page_template( $template ) {
return is_home() ? '' : $template;
}
add_filter( 'frontpage_template', 'themeslug_filter_front_page_template' );
This method causes WordPress to bypass the front-page.php template file altogether when the blog posts index is being displayed.
Adding custom query loops to front-page.php
If the front-page.php template file includes a default WordPress Loop, like so:
&lt;?php
if ( have_posts() ) : while ( have_posts() ) : the_post();
// do something
endwhile; else:
// no posts found
endif;
That loop applies to the post content of the static page assigned to ‘Settings > Reading ->Posts page’.
To display custom loops (latest blog posts, custom/featured content, etc.), add secondary loop queries using calls to WP_Query. For example, to show the 3 latest blog posts:
$latest_blog_posts = new WP_Query( array( 'posts_per_page' =&gt; 3 ) );
if ( $latest_blog_posts-&gt;have_posts() ) : while ( $latest_blog_posts-&gt;have_posts() ) : $latest_blog_posts-&gt;the_post();
// Loop output goes here
endwhile; endif;
Pagination
Static front pages are not intended to be paged. None of the WordPress Previous / Next page link functions work with a static front page. Pagination on a static front page uses the page query variable, not the paged variable. See the WP_Query for details.

Custom Headers
Custom Header
Custom headers allow site owners to upload their own “title” image to their site, which can be placed at the top of certain pages. These can be customized and cropped by the user through a visual editor in the Appearance > Header section of the admin panel. You may also place text beneath or on top of the header. To support fluid layouts and responsive design, these headers may also be flexible. Headers are placed into a theme using 
get_custom_header(), but they must first be added to your functions.php file using 
add_theme_support(). Custom headers are optional.
To set up a basic, flexible, custom header with text you would include the following code:
<?php
function themename_custom_header_setup() {
	$args = array(
		'default-image'      => get_template_directory_uri() . 'img/default-image.jpg',
		'default-text-color' => '000',
		'width'              => 1000,
		'height'             => 250,
		'flex-width'         => true,
		'flex-height'        => true,
	);
	add_theme_support( 'custom-header', $args );
}
add_action( 'after_setup_theme', 'themename_custom_header_setup' );
The 
after_setup_theme hook is used so that custom headers are registered after the theme is loaded.
What are Custom Headers?
When you enable Custom Headers in your theme, users can change their header image using the WordPress theme Customizer. This gives users more control and flexibility over the look of their site.
Add Custom Header Support to your Theme
To enable Custom Headers in your theme, add the following to your 
functions.php file:
add_theme_support( 'custom-header' );
When enabling Custom Headers, you can configure several other options by passing along arguments to the 
add_theme_support() function.
You can pass specific configuration options to the 
add_theme_support function using an array:
<?php
function themename_custom_header_setup() {
	$defaults = array(
		// Default Header Image to display.
		'default-image'          => get_template_directory_uri() . '/images/headers/default.jpg',
		// Display the header text along with the image.
		'header-text'            => false,
		// Header text color default.
		'default-text-color'     => '000',
		// Header image width (in pixels).
		'width'                  => 1000,
		// Header image height (in pixels).
		'height'                 => 198,
		// Header image random rotation default.
		'random-default'         => false,
		// Enable upload of image file in admin.
		'uploads'                => false,
		// Function to be called in theme head section.
		'wp-head-callback'       => 'wphead_cb',
		// Function to be called in preview page head section.
		'admin-head-callback'    => 'adminhead_cb',
		// Function to produce preview markup in the admin screen.
		'admin-preview-callback' => 'adminpreview_cb',
	);
}
add_action( 'after_setup_theme', 'themename_custom_header_setup' );
Flexible Header Image
If flex-height or flex-width are not included in the array, height and width will be fixed sizes. If flex-height and flex-width are included, height and width will be used as suggested dimensions instead.
Header text
By default, the user will have the option of whether or not to display header text over the image. There is no option to force the header text on the user, but if you want to remove the header text completely, you can set ‘header-text’ to ‘false’ in the arguments. This will remove the header text and the option to toggle it.
Examples
Set a custom header image
When the user first installs your theme, you can include a default header that will be selected before they choose their own header. This allows users to set up your theme more quickly and use your default image until they’re ready to upload their own.
Set a default header image 980px width and 60px height:
<?php
$header_info = array(
	'width'         => 980,
	'height'        => 60,
	'default-image' => get_template_directory_uri() . '/images/sunset.jpg',
);
add_theme_support( 'custom-header', $header_info );
$header_images = array(
	'sunset' => array(
		'url'           => get_template_directory_uri() . '/images/sunset.jpg',
		'thumbnail_url' => get_template_directory_uri() . '/images/sunset_thumbnail.jpg',
		'description'   => 'Sunset',
	),
	'flower' => array(
		'url'           => get_template_directory_uri() . '/images/flower.jpg',
		'thumbnail_url' => get_template_directory_uri() . '/images/flower_thumbnail.jpg',
		'description'   => 'Flower',
	),
);
register_default_headers( $header_images );
Do not forget to call register_default_headers() to register a default image. In this example, 
sunset.jpg is the default image and 
flower.jpg is an alternative selection in Customizer.
From Administration Screen, Click Appearance > Header to display Header Image menu in Customizer. Notice that width and height specified in add_theme_support() is displayed as recommended size, and 
flower.jpg is shown as selectable option.
Use flexible headers
By default, the user will have to crop any images they upload to fit in the width and height you specify. However, you can let users upload images of any height and width by specifying ‘flex-width’ and ‘flex-height’ as true. This will let the user skip the cropping step when they upload a new photo.
Set flexible headers:
<?php
$args = array(
	'flex-width'    => true,
	'width'         => 980,
	'flex-height'   => true,
	'height'        => 200,
	'default-image' => get_template_directory_uri() . '/images/header.jpg',
);
add_theme_support( 'custom-header', $args );
update your 
header.php file to:
<img alt="" src="<?php header_image(); ?>" width="<?php echo absint( get_custom_header()->width ); ?>" height="<?php echo absint( get_custom_header()->height ); ?>">
Displaying Custom Header
To display the custom header, function get_header_image() retrieves the header image. get_custom_header() gets the custom header data.
E.g. below shows how custom header images can be used to display the header in the theme. The below code goes into header.php file.
<?php if ( get_header_image() ) : ?>
	<div id="site-header">
		<a href="<?php echo esc_url( home_url( '/' ) ); ?>" rel="home">
			<img src="<?php header_image(); ?>" width="<?php echo absint( get_custom_header()->width ); ?>" height="<?php echo absint( get_custom_header()->height ); ?>" alt="<?php echo esc_attr( get_bloginfo( 'name', 'display' ) ); ?>">
		</a>
	</div>
<?php endif; ?>
Backwards Compatibility
Custom Headers are supported in WordPress 3.4 and above. If you’d like your theme to support WordPress installations that are older than 3.4, you can use the following code instead of 
add_theme_support( ‘custom-header’);
<?php
global $wp_version;
if ( version_compare( $wp_version, '3.4', '>=' ) ) :
	add_theme_support( 'custom-header' );
else :
	add_custom_image_header( $wp_head_callback, $admin_head_callback );
endif;
Function Reference
header_image() Display header image URL.
get_header_image() Retrieve header image for custom header.
get_custom_header() Get the header image data.
get_random_header_image() Retrieve header image for custom header.
add_theme_support() Registers theme support for a given feature.
register_default_headers() Registers a selection of default headers to be displayed by the Customizer.

Custom Logo
What is a Custom Logo?
Using a custom logo allows site owners to upload an image for their website, which can be placed at the top of their website. It can be uploaded from Appearance > Header, in your admin panel. The custom logo support should be added first to your theme using 
add_theme_support(), and then be called in your theme using 
the_custom_logo(). A custom logo is optional, but theme authors should use this function if they include a logo to their theme.
Adding Custom Logo support to your Theme
To enable the use of a custom logo in your theme, add the following to your 
functions.php file:
add_theme_support( 'custom-logo' );
When enabling custom logo support, you can configure five parameters by passing along arguments to the 
add_theme_support() function using an array:
function themename_custom_logo_setup() {
$defaults = array(
'height'               => 100,
'width'                => 400,
'flex-height'          => true,
'flex-width'           => true,
'header-text'          => array( 'site-title', 'site-description' ),
'unlink-homepage-logo' => true,
);
add_theme_support( 'custom-logo', $defaults );
}
add_action( 'after_setup_theme', 'themename_custom_logo_setup' );
The after_setup_theme hook is used so that the custom logo support is registered after the theme has loaded.
height
Expected logo height in pixels. A custom logo can also use built-in image sizes, such as 
thumbnail, or register a custom size using 
add_image_size().
width Expected logo width in pixels. A custom logo can also use built-in image sizes, such as 
thumbnail, or register a custom size using 
add_image_size().
flex-height
Whether to allow for a flexible height.
flex-width Whether to allow for a flexible width.
header-text Classes(s) of elements to hide. It can pass an array of class names here for all elements constituting header text that could be replaced by a logo.
unlink-homepage-logo
*If the 
unlink-homepage-logo parameter is set to true,*logo images inserted using 
get_custom_logo() or 
the_custom_logo() will no longer link to the homepage when visitors are on that page. In an effort to maintain the styling given to the linked image, the unlinked logo image is inside a 
span tag with the same “custom-logo-link” class.
Displaying the custom logo in your theme
A custom logo can be displayed in the theme using 
the_custom_logo() function. But it’s recommended to wrap the code in a 
function_exists() call to maintain backward compatibility with the older versions of WordPress, like this:
if ( function_exists( 'the_custom_logo' ) ) {
	the_custom_logo();
}
Generally logos are added to the 
header.php file of the theme, but it can be elsewhere as well.
If you want to get your current logo URL (or use your own markup) instead of the default markup, you can use the following code:
$custom_logo_id = get_theme_mod( 'custom_logo' );
$logo = wp_get_attachment_image_src( $custom_logo_id , 'full' );
if ( has_custom_logo() ) {
	echo '<img src="' . esc_url( $logo[0] ) . '" alt="' . get_bloginfo( 'name' ) . '">';
} else {
	echo '<h1>' . get_bloginfo('name') . '</h1>';
}
Custom logo template tags
To manage displaying a custom logo in the front-end, these three template tags can be used:
get_custom_logo() - Returns markup for a custom logo.
the_custom_logo() - Displays markup for a custom logo.
has_custom_logo() - Returns a boolean true/false, whether a custom logo is set or not.

Featured Images & Post Thumbnails
Featured images (also sometimes called Post Thumbnails) are images that represent an individual Post, Page, or Custom Post Type. When you create your Theme, you can output the featured image in a number of different ways, on your archive page, in your header, or above a post, for example.
Enabling Support for Featured Image
Themes must declare support for the Featured Image function before the Featured Image interface will appear on the Edit screen. Support is declared by putting the following in your theme’s functions.php file:
add_theme_support( 'post-thumbnails' );
To enable Featured Image only for specific post types, see add_theme_support()
Setting a Featured Image
Once you add support for Featured Images, the Featured Image meta box will be visible on the appropriate content item’s Edit screens. If a user is unable to see it, they can enable it in their screen options.
By default, the Featured Image meta box is displayed in the sidebar of the Edit Post and Edit Page screens.
Function Reference
add_image_size() – Register a new image size.
set_post_thumbnail_size() – Registers an image size for the post thumbnail.
has_post_thumbnail() – Check if post has an image attached.
the_post_thumbnail() – Display Post Thumbnail.
get_the_post_thumbnail() – Retrieve Post Thumbnail.
get_post_thumbnail_id() – Retrieve Post Thumbnail ID.
Image Sizes
The default image sizes of WordPress are “Thumbnail”, “Medium”, “Large” and “Full Size” (the original size of the image you uploaded). These image sizes can be configured in the WordPress Administration Media panel under >Settings > Media. You can also define your own image size by passing an array with your image dimensions:
the_post_thumbnail(); // Without parameter ->; Thumbnail
the_post_thumbnail( 'thumbnail' ); // Thumbnail (default 150px x 150px max)
the_post_thumbnail( 'medium' ); // Medium resolution (default 300px x 300px max)
the_post_thumbnail( 'medium_large' ); // Medium-large resolution (default 768px x no height limit max)
the_post_thumbnail( 'large' ); // Large resolution (default 1024px x 1024px max)
the_post_thumbnail( 'full' ); // Original image resolution (unmodified)
the_post_thumbnail( array( 100, 100 ) ); // Other resolutions (height, width)
Add Custom Featured Image Sizes
In addition to defining image sizes individually using
the_post_thumbnail( array(  ,  ) );
you can create custom featured image sizes in your theme’s functions file that can then be called in your theme’s template files.
add_image_size( 'category-thumb', 300, 9999 ); // 300 pixels wide (and unlimited height)
Here is an example of how to create custom Featured Image sizes in your theme’s 
functions.php file.
if ( function_exists( 'add_theme_support' ) ) {
    add_theme_support( 'post-thumbnails' );
    set_post_thumbnail_size( 150, 150, true ); // default Featured Image dimensions (cropped)
    // additional image sizes
    // delete the next line if you do not need additional image sizes
    add_image_size( 'category-thumb', 300, 9999 ); // 300 pixels wide (and unlimited height)
}
Set the Featured Image Output Size
To be used in the current Theme’s functions.php file.
You can use 
set_post_thumbnail_size() to set the default Featured Image size by resizing the image proportionally (that is, without distorting it):
set_post_thumbnail_size( 50, 50 ); // 50 pixels wide by 50 pixels tall, resize mode
Set the default Featured Image size by cropping the image (either from the sides, or from the top and bottom):
set_post_thumbnail_size( 50, 50, true ); // 50 pixels wide by 50 pixels tall, crop mode
Styling Featured Images
Featured Images are given a class “wp-post-image”. They also get a class depending on the size of the thumbnail being displayed. You can style the output with these CSS selectors:
img.wp-post-image
img.attachment-thumbnail
img.attachment-medium
img.attachment-large
img.attachment-full
You can also give Featured Images their own classes by using the attribute parameter in the_post_thumbnail().
Display the Featured Image with a class “alignleft”:
the_post_thumbnail( 'thumbnail', array( 'class' => 'alignleft' ) );
Examples
Default Usage
// check if the post or page has a Featured Image assigned to it.
if ( has_post_thumbnail() ) {
    the_post_thumbnail();
}
To return the Featured Image for use in your PHP code instead of displaying it, use: get_the_post_thumbnail()
// check for a Featured Image and then assign it to a PHP variable for later use
if ( has_post_thumbnail() ) {
    $featured_image = get_the_post_thumbnail();
}
Linking to Post Permalink or Larger Image
Don’t use these two examples together in the same Theme.
Example 1. To link Post Thumbnails to the Post Permalink in a specific loop, use the following within your Theme’s template files:
<?php if ( has_post_thumbnail()) : ?>
    <a href="<?php the_permalink(); ?>" alt="<?php the_title_attribute(); ?>">
        <?php the_post_thumbnail(); ?>
    </a>
<?php endif; ?>
Example 2. To link all Post Thumbnails on your website to the Post Permalink, put this in the current Theme’s functions.php file:
add_filter( 'post_thumbnail_html', 'my_post_image_html', 10, 3 );
function my_post_image_html( $html, $post_id, $post_image_id ) {
  $html = '<a href="' . get_permalink( $post_id ) . '">' . $html . '</a>';
  return $html;
}
This example links to the “large” Post Thumbnail image size and must be used within The Loop.
if ( has_post_thumbnail()) {
    $large_image_url = wp_get_attachment_image_src( get_post_thumbnail_id(), 'large');
    echo '<a href="' . $large_image_url[0] . '">';
    the_post_thumbnail('thumbnail');
    echo '</a>';
}
Source File
wp-includes/post-thumbnail-template.php
External Resources
Everything you need to know about WordPress 2.9’s post image feature
The Ultimative Guide For the_post_thumbnail In WordPress 2.9
New in WordPress 2.9: Post Thumbnail Images

Internationalization
What is internationalization?
Internationalization is the process of developing your theme, so it can easily be translated into other languages. Internationalization is often abbreviated as 
i18n (because there are 18 letters between the letters i and n).
Why is internationalization important?
WordPress is used all over the world, in countries where English is not the main language. The strings in the WordPress plugins need to be coded in a special way so that can be easily translated into other languages. As a developer, you may not be able to provide localizations for all your users; however, a translator can successfully localize the theme without needing to modify the source code itself.
How to internationalize your theme?
For the text in the theme to be able to be translated easily the text should not be hardcoded in the theme but be passed as an argument through one of the localization functions in WordPress.
The following example could not be translated unless the translator modified the source code which is not very efficient.
<h1>Settings Page</h1>
By passing the string through a localization function it can it can be easily parsed to be translated.
<h1><?php _e( 'Settings Page' ); ?></h1>
WordPress uses gettext libraries to be able to add the translations in PHP. In WordPress you should use the WordPress localization functions instead of the native PHP gettext-compliant translation functions.
Text Domain
The text domain is the second argument that is used in the internationalization functions. The text domain is a unique identifier, allowing WordPress to distinguish between all of the loaded translations. The text domain is only needed to be defined for themes and plugins.
Themes that are hosted on WordPress.org the text domain must match the slug of your theme URL (
wordpress.org/themes/<slug>). This is needed so that the translations from translate.wordpress.org work correctly.
The text domain name must use dashes and not underscores and be lowercase. For example, if the theme’s name 
My Theme is defined in the 
style.css or it is contained in a folder called 
my-theme the text domain should be 
my-theme.
The text domain is used in three different places:
In the 
style.css theme header
As an argument in the localization functions
As an argument when loading the translations using 
load_theme_textdomain() or  
load_child_theme_textdomain()
style.css theme header
The text domain is added to the 
style.css header so that the theme meta-data like the description can be translated even when the theme is not enabled. The text domain should be same as the one used when loading the text domain.
Example:
/*
* Theme Name: My Theme
* Author: Theme Author
* Text Domain: my-theme
*/
Domain Path
The domain path is needed when the translations are saved in a directory other than 
languages . This is so that WordPress knows where to find the translation when the theme is not activated. For example, if .mo files are located in the languages folder then Domain Path will be 
/languages and must be written with the first slash. Defaults to the 
languages folder in the theme.
Example:
/*
* Theme Name: My Theme
* Author: Theme Author
* Text Domain: my-theme
* Domain Path: /languages
*/
Add text domain to strings
The text domain should be added as an argument to all of the localization functions for the translations to work correctly.
Example 1:
__( 'Post' )
should become
__( 'Post', 'my-theme' )
Example 2:
_e( 'Post' )
should become
_e( 'Post', 'my-theme' )
Example 3:
_n( '%s post', '%s posts', $count )
should become
_n( '%s post', '%s posts', $count, 'my-theme' )
The text domain should be passed as a string to the localization functions instead of a variable. It allows parsing tools to differentiate between text domains. Example of what not to do:
__( 'Translate me.' , $text_domain );
Loading Translations
The translations in WordPress are saved in 
.po and 
.mo files which need to be loaded. They can be loaded by using the functions 
load_theme_textdomain() or 
load_child_theme_textdomain(). This loads 
{locale}.mo from your theme’s base directory or 
{text-domain}-{locale}.mo from the WordPress theme language folder in 
/wp-content/languages/themes/.
As of version 4.6 WordPress automatically checks the language directory in 
wp-content for translations from translate.wordpress.org. This means that plugins that are translated via translate.wordpress.org do not require 
load_plugin_textdomain() anymore.
If you don’t want to add a 
load_plugin_textdomain() call to your plugin you should set the 
Requires at least: field in your readme.txt to 4.6.
To find out more about the different language and country codes, see the list of languages.
Watch Out
Name your MO file as 
{locale}.mo (e.g. de_DE.po & de_DE.mo) if adding the translation to the theme folder.
Name your MO file as 
{text-domain}-{locale}.mo (e.g my-theme-de_DE.po & my-theme-de_DE.mo) if you are adding the translation to the WordPress theme language folder.
Example:
function my_theme_load_theme_textdomain() {
    load_theme_textdomain( 'my-theme', get_template_directory() . '/languages' );
}
add_action( 'after_setup_theme', 'my_theme_load_theme_textdomain' );
This function should ideally be run within the theme’s 
function.php.
Language Packs
If you’re interested in language packs and how the import to translate.wordpress.org is working, please read the Meta Handbook page about Translations.
Internationalizing your theme
Now that your translations are loaded, you can start writing every string in your theme with Internationalization functions.
Check the Internationalization page on the Common APIs Handbook for more information and best practices.

Localization
What is localization?
Localization describes the subsequent process of translating an internationalized theme. Localization is abbreviated as 
l10n (because there are 10 letters between the l and the n.)
Please refer to the Localization page on the Common APIs handbook to learn how to Localize your theme.

Media
WordPress enables theme developers to customize the look, feel, and functionality of the platform’s core media capabilities.
General
In WordPress you can upload, store, and display a variety of media such as image, video and audio files. Media can be uploaded via the Media > Add New in the Administration Screen, or Add Media button on the Post/Page Editor.
If a media file is uploaded within the edit screen, it will be automatically attached to the current post being created or edited. If it is uploaded via the Media’s Add New Screen or the Media Library Screen, it will be unattached, but may become attached to a post when it is inserted into a post later on.
Retrieving attachment ID or image ID
To retrieve the attachment ID, use 
get_posts() or 
get_children() function. This example retrieves the all attachments of the current post and getting all metadata of attachment by specifying the ID.
// Insert into the Loop
$args = array(
    'post_parent'    => get_the_ID(),
    'post_type'      => 'attachment',
);
$attachments = get_posts( $args );
if ( $attachments ) {
    foreach ( $attachments as $attachment ) {
        $meta_data = wp_get_attachment_metadata( $attachment->ID, false );
    }
}
If you want to retrieve images from the post ID only, specify post_mime_type as image.
$args = array(
    'post_parent'    => get_the_ID(),
    'post_type'      => 'attachment',
    'post_mime_type' => 'image',
);
References
get_posts()
get_children()
wp_get_attachment_metadata()
Special considerations
Compatible media formats
In the Media Library, you can upload any file (with the network administrator’s unfiltered_upload) and not just images or videos but text files, office documents or even binary files. Single site administrators do not have the unfiltered_upload capability by default and requires that definition to be set for the capability to kick in. Audio and Video files are processed by the internal library 
MediaElement.js.
Supported Audio format
Supported Video format
Troubleshooting:
Cannot retrieve attachment
When you cannot get your attached media by 
get_posts() or 
get_children() function, confirm your media is really attached to the post.
From the Administration Screen, Click Media > Library to open the Media Library and confirm the value in “Uploaded to” column of the media.

Navigation Menus
Navigation Menus are customizable menus in your theme. They allow users to add Pages, Posts, Categories, and URLs to the menu. To create a navigation menu you’ll need to register it, and then display the menu in the appropriate location in your theme.
Register Menus
In your theme’s functions.php, you need to register your menu(s). This sets the name that will appear at Appearance -> Menus.
First of all, you will use register_nav_menus() to register the menu.
In this example, two locations are added to the “Manage Locations” tab: “Header Menu” and “Extra Menu”.
function register_my_menus() {
  register_nav_menus(
    array(
      'header-menu' => __( 'Header Menu' ),
      'extra-menu' => __( 'Extra Menu' )
     )
   );
 }
 add_action( 'init', 'register_my_menus' );
Display Menus
Once you’ve registered your menus, you need to use wp_nav_menu() to tell your theme where to display them. For example, add the following code to your 
header.php file to display the header-menu that was registered above.
wp_nav_menu( array( 'theme_location' => 'header-menu' ) );
A full list of parameters can be found in the wp_nav_menu() page in the function reference
Repeat this process for any additional menus you want to display in your theme. Optionally, you can add a container class which allows you to style the menu with CSS.
wp_nav_menu(
  array(
    'theme_location' => 'extra-menu',
    'container_class' => 'my_extra_menu_class'
  )
);
A full list of CSS Classes can be found in the wp_nav_menu() page in the function reference. You can use these to style your menus.
Display Additional Contents
Below is a simplified version of the Twenty Seventeen footer social menu, which displays 
span elements before and after the menu item label text.
wp_nav_menu(
  array(
    'menu' => 'primary',
    'link_before' => '<span class="screen-reader-text">',
    'link_after' => '</span>',
  )
);
The output will display as…
[html]
  
  
  
Twitter  
  
  
  
[/html]
To display text between the 
<li> and 
<a> elements for each menu item, use 
before and 
after parameters.
Define Callback
By default, WordPress displays the first non-empty menu when the specified menu or location is not found, or generates a Page menu when there is no custom menu selected. To prevent this, use the 
theme_location and 
fallback_cb parameters.
wp_nav_menu(
  array(
    'menu' => 'primary',
    // do not fall back to first non-empty menu
    'theme_location' => '__no_such_location',
    // do not fall back to wp_page_menu()
    'fallback_cb' => false
  )
);

Pagination
Pagination allows your user to page back and forth through multiple pages of content.
WordPress can use pagination when:
Viewing lists of posts when more posts exist than can fit on one page, or
Breaking up longer posts by manually by using the following tag: 
<!--nextpage-->
Using Pagination to Navigate Post Lists
The most common use for pagination in WordPress sites is to break up long lists of posts into separate pages. Whether you’re viewing a category, archive, or default index page for a blog or site, WordPress only shows 10 posts per page by default. Users can change the number of posts that appear on each page on the Reading screen: Admin > Settings > Reading.
Examples
Loop with Pagination
This simplified example shows where you can add pagination functions for the main loop. Add the functions just before or after the loop.
<?php if ( have_posts() ) : ?>
    <!-- Start the pagination functions before the loop. -->
    <div class="nav-previous alignleft"><?php next_posts_link( 'Older posts' ); ?></div>
    <div class="nav-next alignright"><?php previous_posts_link( 'Newer posts' ); ?></div>
    <!-- End the pagination functions before the loop. -->
	<!-- Start of the main loop. -->
	<?php while ( have_posts() ) : the_post();  ?>
	<!-- the rest of your theme's main loop -->
    <?php endwhile; ?>
    <!-- End of the main loop -->
    <!-- Start the pagination functions after the loop. -->
    <div class="nav-previous alignleft"><?php next_posts_link( 'Older posts' ); ?></div>
    <div class="nav-next alignright"><?php previous_posts_link( 'Newer posts' ); ?></div>
    <!-- End the pagination functions after the loop. -->
<?php else : ?>
	<?php _e( 'Sorry, no posts matched your criteria.' ); ?>
<?php endif; ?>
Methods for displaying pagination links
When using any of these pagination functions outside the template file with the loop that is being paginated, you must call the global variable $wp_query.
function your_themes_pagination() {
	global $wp_query;
	echo paginate_links();
}
WordPress has numerous functions for displaying links to other pages in your loop. Some of these functions are only used in very specific contexts. You would use a different function on a single post page then you would on a archive page. The following section covers archive template pagination functions. The section after that cover single post pagination.
Simple Pagination
posts_nav_link
One of the simplest methods is posts_nav_link(). Simply place the function in your template after your loop. This generates both links to the next page of posts and previous page of posts where applicable. This function is ideal for themes that have simple pagination requirements.
posts_nav_link();
next_posts_link & prev_posts_link
When building a theme, use next_posts_link() and prev_posts_link(). to have control over where the previous and next posts page link appears.
next_posts_link();
previous_posts_link();
If you need to pass the pagination links to a PHP variable, you can use get_next_posts_link() and get_previous_posts_link().
$next_posts = get_next_posts_link();
$prev_posts = get_previous_posts_link();
Numerical Pagination
When you have many pages of content it is a better experience to display a list of page numbers so the user can click on any one of the page links rather then having to repeatedly click next or previous posts. WordPress provides several functions for automatically displaying a numerical pagination list.
For WordPress 4.1+
If you want more robust pagination options, you can use the_posts_pagination() for WordPress 4.1 and higher. This will output a set of page numbers with links to previous and next pages of posts.
the_posts_pagination();
For WordPress prior to 4.1
If you want your pagination to support older versions of WordPress, you must use paginate_links().
echo paginate_links();
Pagination Between Single Posts
All of the previous functions should be used on index and archive pages. When you are viewing a single blog post, you must use prev_post_link and next_post_link. Place the following functions below the loop on your single.php.
previous_post_link();
next_post_link();
Pagination within a post
WordPress gives you a tag that can be placed in post content to enable pagination for that post:
<!--nextpage-->
If you use that tag in the content, you need to ensure that the wp_link_pages function is placed in your single.php template within the loop.
<?php if ( have_posts() ) : ?>
	<!-- Start of the main loop. -->
	<?php while ( have_posts() ) : the_post(); ?>
		<?php the_content(); ?>
		<?php wp_link_pages(); ?>
	<?php endwhile; ?>
	<!-- End of the main loop. -->
<?php endif; ?>

Post Formats
A Post Format is used by a theme for presenting posts in a certain format and style. The Post Formats feature provides a standardized list of formats available to all themes that support the feature. A theme may not support every format on the list; in such a case, it is good form to make this known to users.
A theme cannot introduce formats not on the standardized list, even through plugins. This standardization ensures compatibility between themes and a way for external tools to use the feature in a consistent fashion.
In short, with a theme that supports Post Formats, a blogger can change how a post looks by choosing a Post Format.
Using Asides as an example, in the past, a category called Asides was created, and posts were assigned that category, and then displayed differently based on styling rules from post_class() or from in_category(‘asides’).
With Post Formats, the new approach allows a theme to add support for a Post Format (e.g. add_theme_support(‘post-formats’, array(‘aside’))), and then the post format can be selected in the Publish meta box when saving the post. A function call of get_post_format($post->ID) can be used to determine the format, and post_class() will also create the “format-asides” class, for pure-css styling.
Supported Formats
The following Post Formats are available, if supported by the theme.
Note that while actual post content won’t change, the theme can display a post differently based on the format chosen. How posts are displayed is entirely up to the theme, but here are some general guidelines on typical uses for the different Post Formats.
aside – Typically styled without a title. Similar to a Facebook note update.
gallery – A gallery of images. Post will likely contain a gallery shortcode and will have image attachments.
link – A link to another site. Themes may wish to use the first  tag in the post content as the external link for that post. An alternative approach could be if the post consists only of a URL, then that will be the URL and the title (post_title) will be the name attached to the anchor for it.
image – A single image. The first  tag in the post could be considered the image. Alternatively, if the post consists only of a URL, that will be the image URL and the title of the post (post_title) will be the title attribute for the image.
quote – A quotation. Probably will contain a blockquote holding the quote content. Alternatively, the quote may be just the content, with the source/author being the title.
status – A short status update, similar to a Twitter status update.
video – A single video. The first  tag or object/embed in the post content could be considered the video. Alternatively, if the post consists only of a URL, that will be the video URL. May also contain the video as an attachment to the post, if video support is enabled on the blog (like via a plugin).
audio – An audio file. Could be used for Podcasting.
chat – A chat transcript, like so:
John: foo
Mary: bar
John: foo 2
When writing or editing a Post, “Standard” designates that no Post Format is specified. Also if an invalid format is specified, “Standard” (no format) is applied by default.
Function Reference
Main Functions
set_post_format()
get_post_format()
has_post_format()
Other Functions
get_post_format_link()
get_post_format_string()
Adding Theme Support
Themes need to use add_theme_support() in the functions.php file to tell WordPress which post formats to support by passing an array of formats like so:
<?php
function themename_post_formats_setup() {
	add_theme_support( 'post-formats', array( 'aside', 'gallery' ) );
}
add_action( 'after_setup_theme', 'themename_post_formats_setup' );
The after_setup_theme hook is used so that the post formats support is registered after the theme has loaded.
Adding Post Type Support
Post Types need to use add_post_type_support() in the functions.php file to tell WordPress which post formats to support:
<?php
function themename_custom_post_formats_setup() {
	// add post-formats to post_type 'page'
	add_post_type_support( 'page', 'post-formats' );
	// add post-formats to post_type 'my_custom_post_type'
	add_post_type_support( 'my_custom_post_type', 'post-formats' );
}
add_action( 'init', 'themename_custom_post_formats_setup' );
Or in the function register_post_type(), add ‘post-formats’, in ‘supports’ parameter array:
<?php
$args = array(
	'supports' => array( 'title', 'editor', 'author', 'post-formats' ),
);
register_post_type( 'book', $args );
add_post_type_support should be hooked to init hook, as custom post types may not have been registered at after_setup_theme.
Using Formats
In the theme, use get_post_format() to check the format for a post, and change its presentation accordingly. Note that posts with the default format will return a value of FALSE. Alternatively, use the has_post_format() conditional tag:
<?php
if ( has_post_format( 'video' ) ) {
	echo 'This is the video format.';
}
Suggested Styling
An alternate approach to formats is through styling rules. Themes should use the post_class() function in the wrapper code that surrounds the post to add dynamic styling classes. Post formats will cause extra classes to be added in this manner, using the “format-foo” name.
For example, one could hide post titles from status format posts by putting this in your theme’s stylesheet:
.format-status .post-title {
     display: none;
}
Each of the formats lend themselves to a certain type of “style”, as dictated by modern usage. It is well to keep in mind the intended usage for each format when applying styles.
For example, the aside, link, and status formats are simple, short, and minor. These will typically be displayed without title or author information. The aside could contain perhaps a paragraph or two, while the link would be only a sentence with a link to a URL in it. Both the link and aside might have a link to the single post page (using the_permalink()) and would thus allow comments, but the status format very likely would not have such a link.
An image post, on the other hand, would typically just contain a single image, with or without a caption/text to go along with it. An audio/video post would be the same but with audio/video added in. Any of these three could use either plugins or standard Embeds to display their content. Titles and authorship might not be displayed for them either, as the content could be self-explanatory.
The quote format is especially well suited to posting a simple quote from a person with no extra information. If you were to put the quote into the post content alone, and put the quoted person’s name into the title of the post, then you could style the post so as to display the_content() by itself but restyled into a blockquote format, and use the_title() to display the quoted person’s name as the byline.
A chat in particular will probably tend towards a monospaced type display, in many cases. With some styling on the .format-chat, you can make it display the content of the post using a monospaced font, perhaps inside a gray background div or similar, thus distinguishing it visually as a chat session.
Formats in a Child Theme
Child Themes inherit the post formats defined by the parent theme. Calling add_theme_support() for post formats in a child theme must be done at a later priority than that of the parent theme and will override the existing list, not add to it.
<?php
add_action( 'after_setup_theme', 'childtheme_formats', 11 );
function childtheme_formats() {
	 add_theme_support( 'post-formats', array( 'aside', 'gallery', 'link' ) );
}
Calling remove_theme_support(‘post-formats’) will remove it all together.

Sidebars
What are Sidebars
A sidebar is any widgetized area of your theme. Widget areas are places in your theme where users can add their own widgets. You do not need to include a sidebar in your theme, but including a sidebar means users can add content to the widget areas through the Customizer or the Widgets Admin Panel.
Widgets can be employed for a variety of purposes, ranging from listing recent posts to conducting live chats.
The name “sidebars” comes from a time when widget areas were normally created in a long strip to the lefthand or righthand side of a blog. Today, sidebars have evolved beyond their original name. They can be included anywhere on your website. Think of a sidebar as any area that contains widgets.
Registering a Sidebar
To use sidebars, you must register them in 
functions.php.
To begin, 
register_sidebar() has several parameters that should always be defined regardless of whether they are marked as optional. These include x, y, and z.
name – your name for the sidebar. This is the name users will see in the Widgets panel.
id – must be lowercase. You will call this in your theme using the 
dynamic_sidebar function.
description – A description of the sidebar. This will also be shown in the admin Widgets panel.
class – The CSS class name to assign to the widget’s HTML.
before_widget – HTML that is placed before every widget.
after_widget – HTML that is placed after every widget. Should be used to close tags from 
before_widget.
before_title – HTML that is placed before the title of each widget, such as a header tag.
after_title – HTML that is placed after every title. Should be used to close tags from 
before_title.
To register a sidebar we use 
register_sidebar and the 
widgets_init function.
<?php
function themename_widgets_init() {
	register_sidebar( array(
		'name'          => __( 'Primary Sidebar', 'theme_name' ),
		'id'            => 'sidebar-1',
		'before_widget' => '<aside id="%1$s" class="widget %2$s">',
		'after_widget'  => '</aside>',
		'before_title'  => '<h3 class="widget-title">',
		'after_title'   => '</h3>',
	) );
	register_sidebar( array(
		'name'          => __( 'Secondary Sidebar', 'theme_name' ),
		'id'            => 'sidebar-2',
		'before_widget' => '<ul><li id="%1$s" class="widget %2$s">',
		'after_widget'  => '</li></ul>',
		'before_title'  => '<h3 class="widget-title">',
		'after_title'   => '</h3>',
	) );
}
Registering a sidebar tells WordPress that you’re creating a new widget area in Appearance > Widgets that users can drag their widgets to. There are two functions for registering sidebars:
register_sidebar()
register_sidebars()
The first lets you register one sidebar and the second lets you register multiple sidebars.
It is recommended that you register sidebars individually as it allows you to give unique and descriptive names to each sidebar.
Examples
For widget areas in header and footer, it makes sense to name them “Header Widget Area” and “Footer Widget Area”,  rather than “Sidebar 1” and “Sidebar 2” (which is the default). This provides a useful description of where the sidebar is located.
The following code, added to 
functions.php registers a sidebar:
<?php
add_action( 'widgets_init', 'my_register_sidebars' );
function my_register_sidebars() {
	/* Register the 'primary' sidebar. */
	register_sidebar(
		array(
			'id'            => 'primary',
			'name'          => __( 'Primary Sidebar' ),
			'description'   => __( 'A short description of the sidebar.' ),
			'before_widget' => '<div id="%1$s" class="widget %2$s">',
			'after_widget'  => '</div>',
			'before_title'  => '<h3 class="widget-title">',
			'after_title'   => '</h3>',
		)
	);
	/* Repeat register_sidebar() code for additional sidebars. */
}
The code does the following:
register_sidebar – tells WordPress that you’re registering a sidebar
'name' => __( 'Primary Widget Area', 'mytheme' ), – is the widget area’s name that will appear in Appearance > Widgets
'id' => 'sidebar-1' – assigns an ID to the sidebar. WordPress uses ‘id’ to assign widgets to a specific sidebar.
before_widget/
after_widget – a wrapper element for widgets assigned to the sidebar. The “%1$s” and “%2$s” should always be left in 
id and 
class respectively so that plugins can make use of them. By default, WordPress sets these as list items but in the above example they have been altered to div.
before_title/
after_title – the wrapper elements for the widget’s title. By default, WordPress sets it to h2 but using h3 makes it more semantic.
Once your sidebar is registered, you can display it in your theme.
Displaying Sidebars in your Theme
Now that your sidebars are registered, you will want to display them  in  your theme. To do this, there are two steps:
Create the 
sidebar.php template file and display the sidebar using the 
dynamic_sidebar function
Load in your theme using the 
get_sidebar function
Create a Sidebar Template File
A sidebar template contains the code for your sidebar. WordPress recognizes the file  
sidebar.php  and any template file with the name 
sidebar-{name}.php.  This means that you can organize your files with each sidebar in its own template file.
Example:
Create 
sidebar-primary.php
Add the following code:
<div id="sidebar-primary" class="sidebar">
	<?php dynamic_sidebar( 'primary' ); ?>
</div>
Note that 
dynamic_sidebar takes a single parameter of 
$index, which can be either the sidebar’s name or id.
Load your Sidebar
To load your sidebar in your theme, use the 
get_sidebar function. This should be inserted into the template file where you want the sidebar to display. To load the default 
sidebar.php use the following:
<?php get_sidebar(); ?>
To display the Primary sidebar, pass the 
$name parameter to the function:
<?php get_sidebar( 'primary' ); ?>
Customizing your Sidebar
There are lots of ways that you can customize your sidebars. Here are some examples:
Display Default Sidebar Content
You may wish to display content if the user hasn’t added any widgets to the sidebar yet. To do this, you use the 
is_sidebar_active() function to check to see if the sidebar has any widgets. This accepts the 
$index parameter which should be the ID of the sidebar that you wish to check.
This code checks to see if the sidebar is active, if not it displays some content:
<div id="sidebar-primary" class="sidebar">
	<?php if ( is_active_sidebar( 'primary' ) ) : ?>
		<?php dynamic_sidebar( 'primary' ); ?>
	<?php else : ?>
		<!-- Time to add some widgets! -->
	<?php endif; ?>
</div>
Display Default Widgets
You may want your sidebar to be populated with some widgets by default. For example, display the Search, Archive, and Meta Widgets.  To do this you would use:
<div id="primary" class="sidebar">
	<?php do_action( 'before_sidebar' ); ?>
	<?php if ( ! dynamic_sidebar( 'sidebar-primary' ) ) : ?>
		<aside id="search" class="widget widget_search">
			<?php get_search_form(); ?>
		</aside><!-- #search -->
		<aside id="archives" class"widget">
			<h3 class="widget-title"><?php _e( 'Archives', 'shape' ); ?></h3>
			<ul>
				<?php wp_get_archives( array( 'type' => 'monthly' ) ); ?>
			</ul>
		</aside><!-- #archives -->
		<aside id="meta" class="widget">
			<h3 class="widget-title"><?php _e( 'Meta', 'shape' ); ?></h3>
			<ul>
				<?php wp_register(); ?>
				<li><?php wp_loginout(); ?></li>
				<?php wp_meta(); ?>
			</ul>
		</aside><!-- #meta -->
	<?php endif; ?>
</div><!-- #primary -->

Sticky Posts
A Sticky Post is the post will be placed at the top of the front page of posts. This feature is only available for the built-in post type post and not for custom post types.
How to stick a post
Go to Administration Screen > Posts > Add New or Edit
In the right side menu, Click Edit link of Visibility option in Publish group
Click Stick this post to the front page option
Display Sticky Posts
Show Sticky Posts
Display just the first sticky post. At least one post must be designated as a “sticky post” or else the loop will display all posts:
<?php
$sticky = get_option( 'sticky_posts' );
$query  = new WP_Query( 'p=' . $sticky[0] );
Display just the first sticky post, if none return the last post published:
<?php
$args  = array(
	'posts_per_page'      => 1,
	'post__in'            => get_option( 'sticky_posts' ),
	'ignore_sticky_posts' => 1,
);
$query = new WP_Query( $args );
Display just the first sticky post, if none return nothing:
<?php
$args   = array(
	'posts_per_page'      => 1,
	'post__in'            => get_option( 'sticky_posts' ),
	'ignore_sticky_posts' => 1,
);
$query  = new WP_Query( $args );
if ( isset( $sticky[0] ) ) {
	// Insert here your stuff...
}
Don’t Show Sticky Posts
Exclude all sticky posts from the query:
<?php
$args  = array( 'post__not_in' => get_option( 'sticky_posts' ) );
$query = new WP_Query( $args );
Exclude sticky posts from a category. Return ALL posts within the category, but don’t show sticky posts at the top. The ‘sticky posts’ will still show in their natural position (e.g. by date):
<?php
$args  = array(
	'ignore_sticky_posts' => 1,
	'posts_per_page'      => 3,
	'cat'                 => 6,
);
$query = new WP_Query( $args );
Exclude sticky posts from a category. Return posts within the category, but exclude sticky posts completely, and adhere to paging rules:
<?php
$args  = array(
	'cat'                 => 3,
	'ignore_sticky_posts' => 1,
	'post__not_in'        => get_option( 'sticky_posts' ),
	'paged'               => get_query_var( 'paged' ) ? get_query_var( 'paged' ) : 1,
);
$query = new WP_Query( $args );
Use get_query_var( ‘page’ ) if you want this query to work in a Page template that you’ve set as your static front page.
<?php
/* Get all Sticky Posts */
$sticky = get_option( 'sticky_posts' );
/* Sort Sticky Posts, newest at the top */
rsort( $sticky );
/* Get top 5 Sticky Posts */
$sticky = array_slice( $sticky, 0, 5 );
/* Query Sticky Posts */
$query = new WP_Query( array(
	'post__in'            => $sticky,
	'ignore_sticky_posts' => 1,
) );
Style Sticky Posts
To help theme authors perform simpler styling, the post_class() function is used to add class=”…” to DIV, just add:
<div id="post-<?php the_ID(); ?>" <?php post_class(); ?>>
The post_class() outputs the class=”whatever” piece for that div. This includes several different classes of value: post, hentry (for hAtom microformat pages), category-X (where X is the slug of every category the post is in), and tag-X (similar, but with tags). It also adds “sticky” for posts marked as Sticky Posts.
.sticky { color: red; }
The “sticky” class is only added for sticky posts on the first page of the home page (is_home() is true and is_paged() is false)

Widgets
A widget adds content and features to a widget area (also called a sidebar). Widget areas provide a way for users to customize their site. A widget area can appear on multiple pages or on only one page. Your theme might have just one widget area or many of them.
Some examples of ways you can use widget areas are:
Lay out a homepage using widgets. This allows site owners to decide what should appear in each section of their homepage.
Create a footer that users can customize with their own content.
Add a customizable sidebar to a blog.
A widget is a PHP object that outputs some HTML. The same kind of widget can be used multiple times on the same page (e.g. the Text Widget). Widgets can save data in the database (in the options table).
When you create a new kind of widget, it will appear in the user’s Administration Screens at Appearance > Widgets. The user can add the widget to a widget area and customize the widget settings from the WordPress admin.
Built-in versus stand-alone widgets
A set of widgets is included with the default WordPress installation. In addition to these standard widgets, extra widgets can be included by themes or plugins. An advantage of widgets built into themes or plugins is to provide extra features and increase the number of widgets.
A disadvantage is that if a theme is changed or a plugin is deactivated, the plugin or theme widget’s functionality will be lost. However, the data and preferences from the widget will be saved to the options table and restored if the theme or plugin is reactivated.
If you include a widget with your theme, it can only be used if that theme is active. If the user decides to change their theme they will lose access to that widget. However, if the widget is included with a plugin, the user can change their theme without losing access to the widget functionality.
Anatomy of a Widget
Visually, a widget comprises two areas:
Title Area
Widget Options
For example, here is the layout of the built-in text widget in the admin and on the front-end:
A widget form in the admin area.
A widget as it appears to a site visitor.
HTML output for this widget looks like this:
<div id="text-7" class="widget widget_text">
	<div class="widget-wrap">
		<h4 class="widgettitle">
			This is a text widget
		</h4><!-- .widgettitle -->
		<div class="textwidget">
			I can put HTML in here. <a href="http://google.com/">Search me!</a>
		</div><!-- .textwidget -->
	</div><!-- .widget-wrap -->
</div><!-- #text-7 -->
Each widget has its own way of outputting HTML that is relevant to the data being displayed. The wrapper tags for the widget are defined by the widget area in which it is being displayed.
The PHP code necessary to create a widget like the built-in text widget looks like this:
<?php
class My_Widget extends WP_Widget {
	public function __construct() {
		parent::__construct(
			'my-text',  // Base ID
			'My Text'   // Name
		);
		add_action( 'widgets_init', function() {
			register_widget( 'My_Widget' );
		});
	}
	public $args = array(
		'before_title'  => '<h4 class="widgettitle">',
		'after_title'   => '</h4>',
		'before_widget' => '<div class="widget-wrap">',
		'after_widget'  => '</div></div>',
	);
	public function widget( $args, $instance ) {
		echo $args['before_widget'];
		if ( ! empty( $instance['title'] ) ) {
			echo $args['before_title'] . apply_filters( 'widget_title', $instance['title'] ) . $args['after_title'];
		}
		echo '<div class="textwidget">';
		echo esc_html__( $instance['text'], 'text_domain' );
		echo '</div>';
		echo $args['after_widget'];
	}
	public function form( $instance ) {
		$title = ! empty( $instance['title'] ) ? $instance['title'] : esc_html__( '', 'text_domain' );
		$text  = ! empty( $instance['text'] ) ? $instance['text'] : esc_html__( '', 'text_domain' );
		?>
		<p>
			<label for="<?php echo esc_attr( $this->get_field_id( 'title' ) ); ?>"><?php echo esc_html__( 'Title:', 'text_domain' ); ?></label>
			<input class="widefat" id="<?php echo esc_attr( $this->get_field_id( 'title' ) ); ?>" name="<?php echo esc_attr( $this->get_field_name( 'title' ) ); ?>" type="text" value="<?php echo esc_attr( $title ); ?>">
		</p>
		<p>
			<label for="<?php echo esc_attr( $this->get_field_id( 'Text' ) ); ?>"><?php echo esc_html__( 'Text:', 'text_domain' ); ?></label>
			<textarea class="widefat" id="<?php echo esc_attr( $this->get_field_id( 'text' ) ); ?>" name="<?php echo esc_attr( $this->get_field_name( 'text' ) ); ?>" type="text" cols="30" rows="10"><?php echo esc_attr( $text ); ?></textarea>
		</p>
		<?php
	}
	public function update( $new_instance, $old_instance ) {
		$instance          = array();
		$instance['title'] = ( ! empty( $new_instance['title'] ) ) ? strip_tags( $new_instance['title'] ) : '';
		$instance['text']  = ( ! empty( $new_instance['text'] ) ) ? $new_instance['text'] : '';
		return $instance;
	}
}
$my_widget = new My_Widget();
The code above will be explained in detail later in the article.
Developing Widgets
To create and display a widget, you need to do the following:
Create your widget’s class by extending the standard WP_Widget class and some of its functions.
Register your widget so that it’s made available in the Widgets screen.
Make sure that your theme has at least one widget area in which to add the widgets.
Your Widget Class
The WP_Widget class is located in wp-includes/class-wp-widget.php
<?php
class My_Widget extends WP_Widget {
	public function __construct() {
		// actual widget processes
	}
	public function widget( $args, $instance ) {
		// outputs the content of the widget
	}
	public function form( $instance ) {
		// outputs the options form in the admin
	}
	public function update( $new_instance, $old_instance ) {
		// processes widget options to be saved
	}
}
The documentation for each of these functions can be found in the widget class code:
construct: Set up your widget with a description, name, and display width in your admin.
widget: Process the widget options and display the HTML on your page. The 
$args parameter provides the HTML you can use to display the widget title class and widget content class.
form: Display the form that will be used to set the options for your widget. If your widget doesn’t have any options, you can skip this function (although it is still best practice to include it even if it’s empty).
update: Save the widget options to the database. If your widget doesn’t have any options, you can skip this function (although it is still best practice to include it even if it’s empty).
Registering a Widget
The register_widget() function is used to register a widget.
Call this function using the widgets_init hook:
<?php
add_action( 'widgets_init', 'wpdocs_register_widgets' );
function wpdocs_register_widgets() {
	register_widget( 'My_Widget' );
}
The HTML that wraps the widget, as well as the class for the title and widget content, is specified at the time you register the widget area using register_sidebar().
Examples
Example Text Widget
To build the text widget from the example at the beginning of this article. You will start by setting up a widget class that extends the WP_Widget class.
In the class constructor you will call the parent constructor and pass it your widget’s base ID and name. Also in the class constructor you will hook into the 
widgets_init action to register your widget.
Next you will declare the arguments you will use when creating your widget. There are four arguments you must define, 
before_title, 
after_title, 
before_widget, and 
after_widget. These arguments will define the code that wraps your widgets title and the widget itself.
After defining your arguments, you will define the widgets function. This function takes two parameters, the 
$args array from before, and the 
$instance of the widget, and is the function that will process options from the form and display the HTML for the widget on the front-end of your site. In the example above the widget function simply outputs the widget title, while passing it through the 
widget_title filter. It then out puts a simple widget wrapper and the content of the widget’s text field. As outlined in the example, you can access the options from the widget that are stored in the 
$instance.
Next you will define the form function. This function takes one parameter, 
$instance, and outputs the form that the user uses to create the widget in the Widgets admin screen. In the example above, the function starts by defining the 
$title and 
$text variables and setting them to the previously entered values, if those values exist. Then it outputs a simple form with a text field for the title and a textarea for the text content.
Lastly you will define the update function. This function takes two parameters, 
$new_instance and 
$old_instance, and is responsible for updating your widgets with new options when they are submitted. Here you simply define 
$instance as an empty array. You then set the title and text keys to the 
$new_instance values if they exist. You then return 
$instance.
Finally, when all of the above is defined, you instantiate your new widget class and test your work.
Sample Widget
<?php
/**
 * Adds Foo_Widget widget.
 */
class Foo_Widget extends WP_Widget {
	/**
	 * Register widget with WordPress.
	 */
	public function __construct() {
		parent::__construct(
			'foo_widget', // Base ID
			'Foo_Widget', // Name
			array( 'description' => __( 'A Foo Widget', 'text_domain' ) ) // Args
		);
	}
	/**
	 * Front-end display of widget.
	 *
	 * @see WP_Widget::widget()
	 *
	 * @param array $args     Widget arguments.
	 * @param array $instance Saved values from database.
	 */
	public function widget( $args, $instance ) {
		extract( $args );
		$title = apply_filters( 'widget_title', $instance['title'] );
		echo $before_widget;
		if ( ! empty( $title ) ) {
			echo $before_title . $title . $after_title;
		}
		echo __( 'Hello, World!', 'text_domain' );
		echo $after_widget;
	}
	/**
	 * Back-end widget form.
	 *
	 * @see WP_Widget::form()
	 *
	 * @param array $instance Previously saved values from database.
	 */
	public function form( $instance ) {
		if ( isset( $instance['title'] ) ) {
			$title = $instance['title'];
		} else {
			$title = __( 'New title', 'text_domain' );
		}
		?>
		<p>
			<label for="<?php echo $this->get_field_name( 'title' ); ?>"><?php _e( 'Title:' ); ?></label>
			<input class="widefat" id="<?php echo $this->get_field_id( 'title' ); ?>" name="<?php echo $this->get_field_name( 'title' ); ?>" type="text" value="<?php echo esc_attr( $title ); ?>" />
		 </p>
		<?php
	}
	/**
	 * Sanitize widget form values as they are saved.
	 *
	 * @see WP_Widget::update()
	 *
	 * @param array $new_instance Values just sent to be saved.
	 * @param array $old_instance Previously saved values from database.
	 *
	 * @return array Updated safe values to be saved.
	 */
	public function update( $new_instance, $old_instance ) {
		$instance          = array();
		$instance['title'] = ( ! empty( $new_instance['title'] ) ) ? strip_tags( $new_instance['title'] ) : '';
		return $instance;
	}
} // class Foo_Widget
This sample widget can then be registered in the widgets_init hook:
<?php
// Register Foo_Widget widget
add_action( 'widgets_init', 'register_foo' );
function register_foo() {
	register_widget( 'Foo_Widget' );
}
Example with a Namespace
If you use PHP 5.3 with namespaces you should call the constructor directly as in the following example:
<?php
namespace a\b\c;
class My_Widget_Class extends \WP_Widget {
	public function __construct() {
		parent::__construct( 'baseID', 'name' );
	}
	// ... rest of the functions
}
and call the register widget with:
<?php
// Register Foo_Widget widget
add_action( 'widgets_init', 'register_my_widget' );
function register_my_widget() {
	register_widget( 'a\b\c\My_Widget_Class' );
}
See this answer at stack exchange for more detail.
Special considerations
If you want to use a widget inside another template file, rather than in a sidebar, you can use 
the_widget() to display it programmatically. The function accepts widget class names. You pass the widget class name to the function like this:
<?php the_title(); ?>
<div class="content">
	<?php the_content(); ?>
</div><!-- .content -->
<div class="widget-section">
	<?php the_widget( 'My_Widget_Class' ); ?>
</div><!-- .widget-section -->
You may want to use this approach if you need to use a widget in a specific area on a page, such as displaying a list of events next to a form in a section on the front page of your site or displaying an email capture form on a mega-menu alongside your navigation.

Audio
Audio
You can directly embed audio files and play them back using a simple shortcode [audio]. Supported file types are mp3, ogg, wma, m4a and wav.
Audio shortcode
Following shortcode displays audio player that loads music.mp3 file:
[[audio src="music.mp3"]]
To use the shortcode from template file, use do_shortcode function. When music.mp3 file was stored in (theme_directory)/sounds directory, insert following code into your template file:
$music_file = get_template_directory_uri() . "/sounds/music.mp3";
echo do_shortcode('[[audio mp3=' . $music_file . ']]');
The shortcode creates the audio player as shown in the screenshot below.
Loop and Autoplay
The following basic options are supported:
loop
Allows for the looping of media.
“off” – Do not loop the media. Default.
“on” – Media will loop to beginning when finished and automatically continue playing.
autoplay
Causes the media to automatically play as soon as the media file is ready.
0 – Do not automatically play the media. Default.
1 – Media will play as soon as it is ready.
The following example starts playing music immediately after the page load and loops.
echo do_shortcode('[[audio mp3=' . $music_file . ' loop = "on" autoplay = 1]]');
Styling
If you want to change the look & feel of audio player, you can do so by targeting the default class name of “wp-audio-shortcode”. If you insert following code into your style.css, half width of audio player will be displayed.
.wp-audio-shortcode {
  width: 50%;
}
Supported Audio format
mp3
ogg
wma
m4a
wav
References
For more technical details such as the internal library that enables this function, refer to
https://make.wordpress.org/core/2013/04/08/audio-video-support-in-core/.
Audio Shortcode
Function do_shortcode()

Galleries
Galleries
Image galleries are the best way to showcase your pictures on your WordPress sites. WordPress bundles the Create Gallery feature by default in the media uploader which allows you to create a simple gallery.
Note: Before adding a gallery, you must have images in your media library. Otherwise, you need to upload the images into the library and can proceed on gallery creation.
Gallery shortcode
The Gallery feature allows you to add one or more image galleries to your posts and pages using a simple Shortcode.
The basic form of gallery shortcode is:
[gallery]
If you use the [gallery] shortcode without using the 
ids argument in your post or page, only images that are “attached” to that post or page will be displayed.
If you need to add multiple images with ID’s, use the following sample shortcode
//Note: 10, 205, 552 and 607 are the IDs of respected image.
[gallery ids="10, 205, 552, 607"]
NOTE: find the proper IDs of the images for the gallery. Go to Media library and click on the respected image and ID will appear on the URL.
To use the shortcode from the template file, use the do_shortcode() function. Insert the following code into your template file:
<?php echo do_shortcode( [gallery] ); ?>
If you need to use the shortcode with IDs, insert the following code in your template file:
<?php echo do_shortcode( [gallery ids="10, 205, 552, 607"] ); ?>
Usage
There are may options that may be specified using the below syntax:
[gallery option1="value1" option2="value2"]
If you want to print the gallery directly on the template file, use 
[do\_shortcode()](https://developer.wordpress.org/reference/functions/do_shortcode/)  function like below:
<?php echo do_shortcode( '[gallery option1="value1"]' ); ?>
If you need to filter the shortcodes, the following example gives you some tips
// Note: 'the_content' filter is used to filter the content of the
// post after it is retrieved from the database and before it is 
// printed to the screen.
<?php
$gallery_shortcode = '[gallery id="' . intval( $post->post_parent ) . '"]';
print apply_filters( 'the_content', $gallery_shortcode );
?>
Supported Options
Gallery Shortcodes supports the basic options which are listed below:
Orderby
‘orderby’ specifies the order the thumbnails show up. The default order is ‘menu_order’.
menu_order: You can reorder the images in the Gallery tab of the Add Media popup
title: Order by the title of the image in the Media Library
post_date: Sort by date/time
rand: Order randomly
ID: Specify the post ID
Order
order specify the sort order used to display thumbnail; ASC or DESC. For Example, to sort by ID and DESC:
[gallery order="DESC" orderby="ID"]
If you need to print it on template file, use the do_shortcode() function;
<?php echo do_shortcode( '[gallery]' ); ?>
columns
The Columns options specify the number of columns in the gallery. The default value is 3.
If you want to increase the number of column in the galley, use the following shortcode.
[gallery columns="4"]
If you need to print it on your template file, use the do_shortcode() function;
<?php echo do_shortcode(' [gallery columns="4"] '); ?>
IDs
The IDs option on the gallery shortcode loads images with specific post IDs.
If you want to display the attached image with the specific post ID, follow the following code example.
// Note: remove each space between brackets and 'gallery' and brackets and `123"`.
//Here "123" stands for the post IDs. If you want to display more than
//one ID, separate the IDs by a comma `,`.
[ gallery id="123" ]
Use ‘do_shortcode’ function to print the gallery with IDs on template files like below:
// Note: remove each space between brackets and 'gallery' and brackets and `123"`.
<?php echo do_shortcode(' [ gallery id="123" ] '); ?>
Size
Size determines the image size to use for the thumbnail display. Valid values include “thumbnail”, “medium”, “large”, “full” and any other additional image size that was registered with add_image_size(). The default value is “thumbnail”. The size of the images for “thumbnail”, “medium” and “large” can be configured in WordPress admin panel under Settings > Media.
For example, to display a gallery of medium sized images:
[gallery size="medium"]
Some advanced options are also available on Gallery shortcodes.
itemtag
The name of the HTML tag used to enclose each item in the gallery. The default is “dl”.
icontag
The name of the HTMLtag used to enclose each thumbnail icon in the gallery. The default is “dt”.
captiontag
The name of the HTML tag used to enclose each caption. The default is “dd”.
You are allowed to change the defaults.
[gallery itemtag="div" icontag="span" captiontag="p"]
Link
Specify where you want the image to link. The default value links to the attachment’s permalink. Options:
file – Link directly to image file
none – No link
Example:
[gallery link="file"]
Include
Include allows you to insert an “array” of comma separated attachment IDs to show only the images from these attachments.
[gallery include="23,39,45"]
Exclude
Exclude callows you to insert an “array” of comma separated attachment IDs to not show the images from these attachments. Please note that include and exclude cannot be used together.
[gallery exclude="21,32,43"]
References
For more technical details take a reference from below links
Gallery Shortcode
Function do_shortcode()

Images
Images
This section describes the handling of images in the Media Library. If you want to display the image file located within your theme directory, just specify the location with the img tag, and style it with CSS.
<img alt="" src="" />
Getting img code
To display the image in the Media Library, use 
wp_get_attachment_image() function.
echo wp_get_attachment_image( $attachment->ID, 'thumbnail' );
You will get the following HTML output with the selected thumbnail size
<img width="150" height="150" src="http://example.com/wordpress/wp-content/uploads/2016/11/sample-150x150.jpg" class="attachment-thumbnail size-thumbnail" ... />
You can specify other size such as ‘full’ for original image or ‘medium’ and ‘large’ for the sizes set at Settings > Media in the Administration Screen, or any pair of width and height as array. You’re also free to set custom size strings with add_image_size() ;
echo wp_get_attachment_image( $attachment->ID, array(640, 480) );
Getting URL of image
If you want to get the URL of the image, use 
wp_get_attachment_image_src(). It returns an array (URL, width, height, is_intermediate), or 
false, if no image is available.
<?php 
$image_attributes = wp_get_attachment_image_src( $attachment->ID );
if ( $image_attributes ) : ?>
    <img src="<?php echo $image_attributes[0]; ?>" width="<?php echo $image_attributes[1]; ?>" height="<?php echo $image_attributes[2]; ?>" />
<?php endif; ?>
Alignments
When adding the image in your site, you can specify the image alignment as right, left, center or none. WordPress core automatically adds CSS classes to align the image:
alignright
alignleft
aligncenter
alignnone
This is the sample output when center align si chosen
<img class="aligncenter size-full wp-image-131" src= ... />
In order to take advantage of these CSS classes for alignment and text wrapping, your theme must include the styles in a stylesheet such as the main stylesheet file. You can use the 
style.css bundled with official themes such as Twenty Seventeen for reference.
Caption
If a Caption was specified to image in the Media Library, HTML 
img element was enclosed by the shortcode [caption] and [/caption].
<div class="mceTemp">
  <dl id="attachment_133" class="wp-caption aligncenter" style="width: 1210px">
    <dt class="wp-caption-dt">
      <img class="size-full wp-image-133" src="http://example.com/wordpress/wp-content/uploads/2016/11/sample.jpg" alt="sun set" width="1200" height="400" />
    </dt>
    <dd class="wp-caption-dd">Sun set over the sea</dd>
  </dl>
</div>
And, it will be rendered as in HTML as the figure tag:
<figure id="attachment_133" style="width: 1200px" class="wp-caption aligncenter">
  <img class="size-full wp-image-133" src="http://example.com/wordpress/wp-content/uploads/2016/11/sample.jpg" alt="sun set" width="1200" height="400" srcset= ... />
  <figcaption class="wp-caption-text">Sun set over the sea</figcaption>
</figure>
Similar to alignments, your theme must include following styles.
wp-caption
wp-caption-text
WebP support and default MIME type of sub size image output
WordPress 5.8 introduces support for WebP image format which provides improved lossless and lossy compression for images on the web. WebP images are around 30% smaller on average than their JPEG or PNG equivalents, resulting in sites that are faster and use less bandwidth. WebP is supported in all modern browsers according to caniuse.
When images are uploaded, WordPress generates smaller sub sizes as defined using 
add_image_size(). By default, WordPress will generate these sub sizes in the same format as the original. Because of the performance benefits of the WebP format, it may be desirable for sub sizes to be generated in WebP instead of the original format.
image_editor_output_format filter hook can be used to change the file format used for image sub sizes. This can be used to switch all sub sizes to WebP, or any other desired format (JPEG, etc.).
The following example shows how to generate all sub sizes for JPG images using WebP:
<?php
function wporg_image_editor_output_format( $formats ) {
    $formats['image/jpg'] = 'image/webp';
 
    return $formats;
}
add_filter( 'image_editor_output_format', 'wporg_image_editor_output_format' );
Note: both the GD and ImageMagick libraries support the WebP format in both lossy and lossless. However, only ImageMagick supports animated images.
Setting the output format to WebP will verify if the web server supports it, and if not it will not change the format, i.e. won’t work.
References
wp_get_attachment_image()
wp_get_attachment_image_src()
Styling Images in Posts and Pages
CSS (Codex)

Video
Video
The WordPress video feature allows you to embed video files and play them back using a simple shortcode [video]. Supported file types are mp4, m4v, webm, ogv, wmv and flv.
Video shortcode
Following shortcode displays video player that loads pepper.mp4 file:
[video src="pepper.mp4"]
To use the shortcode in the template file, use the do_shortcode() function. If the video file is stored in in your theme directory, get the file url directly using get_template_directory_uri() or get_stylesheet_uri() :
$video_file = get_template_directory_uri() . "/videos/pepper.mp4";
echo do_shortcode( '[video mp4=' . $video_file . ']' );
The following video player will be loaded.
Loop and Autoplay
The shortcode video has the same option with audio. Refer to the related section for the loop and autoplay options.
The following example starts playing the video immediately after the page load and loops:
echo do_shortcode( '[video mp4=' . $video_file . ' loop="on" autoplay=1]' );
Initial image and Styling
The following basic options are supported:
Poster
Defines image to show as placeholder before the media plays.
The following same code takes 
album_cover.jpg stored in 
(theme directory)/images folder as the initial image:
echo do_shortcode( '[video mp4=' . $video_file . ' poster=' . get_template_directory_uri() . '/images/album_cover.jpg]' );
Height
Defines height of the media. Value is automatically detected on file upload. When you omit this option, the media file height is used.
Width
Defines width of the media. Value is automatically detected on file upload. When you omit this option, the media file width is used.
The theme’s content_width sets the maximum width.
The following example will load the audio player with 320 pixels width and 240 pixels height:
echo do_shortcode( '[video mp4=' . $video_file . ' width=320 height=240]' );
Styling
If you want to change look & feel of video player from stylesheet, you can target the class name of “wp-video-shortcode”. If you want to show the audio player like above in 320 x 240 size, insert following code into your stylesheet:
.wp-video-shortcode {
    height: 240px;
    width: 320px;
}
Supported Video format
mp4
m4v
webm
ogv
flv
References
For more technical details such as internal library that enables this function, refer to
https://make.wordpress.org/core/2013/04/08/audio-video-support-in-core/.
Video Shortcode
Function do_shortcode()

List of Conditional Tags
Conditional Tags are a boolean data type that can be used in your Template Files to alter the display of content depending on the conditions that the current page matches. They tell WordPress what code to display under specific conditions. Conditional Tags usually work with PHP if /else Conditional Statements and have a close relation with WordPress Template Hierarchy.
Warning: You can only use conditional query tags after the WP_Query is set up or with an action hook.
Complete List of Conditional Tags
is_front_page()
is_home()
is_front_page()
is_home()
is_admin()
is_network_admin()
is_admin_bar_showing()
is_single()
is_sticky()
is_post_type_hierarchical( $post_type )
is_post_type_archive()
is_comments_popup()
comments_open()
pings_open()
is_page()
is_page_template()
is_category( $category )
is_tag()
is_tax()
has_term()
term_exists( $term, $taxonomy, $parent )
is_taxonomy_hierarchical( $taxonomy )
taxonomy_exists( $taxonomy )
is_author()
is_date()
is_year()
is_month()
is_day()
is_time()
is_new_day()
is_archive()
is_search()
is_404()
is_paged()
is_attachment()
wp_attachment_is_image( $post_id )
is_local_attachment( $url )
is_singular()
post_type_exists( $post_type )
is_main_query()
is_new_day()
is_feed()
is_trackback()
is_preview()
in_the_loop()
is_dynamic_sidebar()
is_active_sidebar()
is_active_widget( $widget_callback, $widget_id )
is_blog_installed()
is_rtl()
is_multisite()
is_main_site()
is_super_admin()
is_user_logged_in()
email_exists( $email )
username_exists( $username )
is_plugin_active( $path )
is_plugin_inactive( $path )
is_plugin_active_for_network( $path )
is_plugin_page()
is_child_theme()
current_theme_supports()
has_post_thumbnail( $post_id )
wp_script_is( $handle, $list )
The Conditions For …
All of the Conditional Tags test to see whether a certain condition is met, and then returns either TRUE or FALSE. The conditions under which various tags output TRUE is listed below. Those tags which can accept parameters are so noted.
The Main Page
is_home()
The Front Page
is_front_page()
The Blog Page
is_front_page()
is_home()
A Single Post Page
is_single()
A PAGE Page
is_page()
is_page_template()
Has Post Thumbnail
has_post_thumbnail( $post_id )
A Single Page, a Single Post, an Attachment or Any Other Custom Post Type
is_singular()
A Category Page
is_category( $category )
A Tag Page
is_tag()
has_tag()
A Taxonomy Page (and related)
is_tax()
has_term()
term_exists( $term, $taxonomy, $parent )
is_taxonomy_hierarchical( $taxonomy )
taxonomy_exists( $taxonomy )
An Author Page
is_author()
A Date Page
is_date()
is_year()
is_month()
is_day()
is_time()
is_new_day()
Any Archive Page
is_archive()
A Search Result Page
is_search()
A 404 Not Found Page
is_404()
Is Dynamic SideBar
is_dynamic_sidebar()
Is Sidebar Active
is_active_sidebar()
Is Widget Active
is_active_widget( $widget_callback, $widget_id )
Is User Logged in
is_user_logged_in()
Email Exists
email_exists( $email )
Username Exists
username_exists( $username )
A Paged Page
is_paged()
Right To Left Reading
is_rtl()
An Attachment
is_attachment()
Attachment Is Image
wp_attachment_is_image( $post_id )
A Local Attachment
is_local_attachment( $url )
Post Type Exists
post_type_exists( $post_type )
Is Main Query
is_main_query()
A New Day
is_new_day()
A Syndication
is_feed()
A Trackback
is_trackback()
A Preview
is_preview()
Has An Excerpt
has_excerpt()
Has A Nav Menu Assigned
has_nav_menu()
Is Blog Installed
is_blog_installed()
Part of a Network (Multisite)
is_multisite()
is_main_site()
is_super_admin()
An Active Plugin
is_plugin_active( $path )
is_plugin_inactive( $path )
is_plugin_active_for_network( $path )
is_plugin_page()
A Child Theme
is_child_theme()
Theme supports a feature
current_theme_supports()
Is Previewed in the Customizer
is_customize_preview()

List of Template Tags
Complete List of Template Tags
Template tags files are stored in the 
wp-includes directory. The files have the suffix of “-template.php” to distinguish them from other WordPress files. There are 9 template tags files:
wp-includes/general-template.php
wp-includes/author-template.php
wp-includes/bookmark-template.php
wp-includes/category-template.php
wp-includes/comment-template.php
wp-includes/link-template.php
wp-includes/post-template.php
wp-includes/post-thumbnail-template.php
wp-includes/nav-menu-template.php
Tags
General tags
wp-includes/general-template.php
get_header()
get_footer()
get_sidebar()
get_template_part()
get_search_form()
wp_loginout()
wp_logout_url()
wp_login_url()
wp_login_form()
wp_lostpassword_url()
wp_register()
wp_meta()
bloginfo()
get_bloginfo()
get_current_blog_id()
wp_title()
single_post_title()
post_type_archive_title()
single_cat_title()
single_tag_title()
single_term_title()
single_month_title()
get_archives_link()
wp_get_archives()
calendar_week_mod()
get_calendar()
delete_get_calendar_cache()
allowed_tags()
wp_enqueue_script()
Author tags
wp-includes/author-template.php
the_author()
get_the_author()
the_author_link()
get_the_author_link()
the_author_meta()
the_author_posts()
the_author_posts_link()
wp_dropdown_users()
wp_list_authors()
get_author_posts_url()
Bookmark tags
wp-includes/bookmark-template.php and 
wp-includes/bookmark.php
wp_list_bookmarks()
get_bookmark()
get_bookmark_field()
get_bookmarks()
Category tags
wp-includes/category-template.php
category_description()
single_cat_title()
the_category()
the_category_rss()
wp_dropdown_categories()
wp_list_categories()
single_tag_title()
tag_description()
the_tags()
wp_generate_tag_cloud()
wp_tag_cloud()
term_description()
single_term_title()
get_the_term_list()
the_terms()
the_taxonomies()
Comment tags
wp-includes/comment-template.php
cancel_comment_reply_link()
comment_author()
comment_author_email()
comment_author_email_link()
comment_author_IP()
comment_author_link()
comment_author_rss()
comment_author_url()
comment_author_url_link()
comment_class()
comment_date()
comment_excerpt()
comment_form_title()
comment_form()
comment_ID()
comment_id_fields()
comment_reply_link()
comment_text()
comment_text_rss()
comment_time()
comment_type()
comments_link()
comments_number()
comments_popup_link()
get_avatar()
next_comments_link()
paginate_comments_links()
permalink_comments_rss()
previous_comments_link()
wp_list_comments()
Link tags
wp-includes/link-template.php
the_permalink()
user_trailingslashit()
permalink_anchor()
get_permalink()
get_post_permalink()
get_page_link()
get_attachment_link()
wp_shortlink_header()
wp_shortlink_wp_head()
edit_bookmark_link()
edit_comment_link()
edit_post_link()
get_edit_post_link()
get_delete_post_link()
edit_tag_link()
get_admin_url()
get_home_url()
get_site_url()
home_url()
site_url()
get_search_link()
get_search_query()
the_feed_link()
the_privacy_policy_link()
get_the_privacy_policy_link()
Post tags
wp-includes/post-template.php
body_class()
next_image_link()
next_post_link()
next_posts_link()
post_class()
post_password_required()
posts_nav_link()
previous_image_link()
previous_post_link()
previous_posts_link()
single_post_title()
the_category()
the_category_rss()
the_content()
the_excerpt()
the_excerpt_rss()
the_ID()
the_meta()
the_tags()
the_title()
get_the_title()
the_title_attribute()
the_title_rss()
wp_link_pages()
get_attachment_link()
wp_get_attachment_link()
the_attachment_link()
the_search_query()
is_attachment()
wp_attachment_is_image()
wp_get_attachment_image()
wp_get_attachment_image_src()
wp_get_attachment_metadata()
get_the_date()
single_month_title()
the_date()
the_date_xml()
the_modified_author()
the_modified_date()
the_modified_time()
the_time()
the_shortlink()
wp_get_shortlink()
Post Thumbnail tags
wp-includes/post-thumbnail-template.php
has_post_thumbnail()
get_post_thumbnail_id()
the_post_thumbnail()
get_the_post_thumbnail()
Navigation Menu tags
wp-includes/nav-menu-template.php
wp_nav_menu()
walk_nav_menu_tree()
See Also
Conditional Tags

Attachment Template Files
Attachments are a special post type that holds information about a file uploaded through the WordPress media upload system, such as its description and name, which can display through several post type – attachment template files.
For images, as an example, the attachment post type links to metadata information, about the size of the images, the thumbnails generated, the location of the image files, the HTML alt text, and even information obtained from EXIF data embedded in the images.
Utilizing attachment templates to gain additional metadata information for uploads, help with SEO efforts.
As shown in the template hierarchy, you are able to display your attachments through several template files in order of fallback:
MIME_type.php and a 
subtype.php
It can be any MIME type (For example: 
image.php, 
video.php, 
application.php). For text/plain, the following path is used (in order):
text_plain.php
plain.php
text.php
attachment.php
single-attachment.php
single.php
singular.php
index.php
MIME_type.php
Attachments are served by template files based on their mime-type. As an example, if your attachment is an image, your can customize how they display through the creation of an 
image.php template file. All images with the 
post_mime_type of image/* will render though your 
image.php template file.
Attachments also support the use of a mime 
subtype.php file. To continue with the image example, you can further customize your theme to support not only an 
image.php file but a 
jpg.php subtype file.
Attachment.php
An attachment page (
attachment.php) is a single post page with the post type of attachment, generated through the creation of an attachment.php. Just like a single post page, which is dedicated to your article, the attachment page provides a dedicated page in attachments in your theme.
Creation of attachment page is as simple as creating an attachment.php file. The attachment.php file then contains code similar to the single.php post page.
<div class="entry-attachment">
	<?php
	$image_size = apply_filters( 'wporg_attachment_size', 'large' );
	echo wp_get_attachment_image( get_the_ID(), $image_size );
	?>
	<?php if ( has_excerpt() ) : ?>
		<div class="entry-caption">
			<?php the_excerpt(); ?>
		</div><!-- .entry-caption -->
	<?php endif; ?>
</div><!-- .entry-attachment -->
Function Reference
get_attachment_template() : Retrieve path of attachment template in current or parent template.

Custom Post Type Template Files
The WordPress theme system supports custom templates for custom post types. Custom templates for the single display of posts belonging to custom post types have been supported since WordPress Version 3.0 and the support for custom templates for archive displays was added in Version 3.1.
Custom Post Type – Template Hierarchy
WordPress will work through the template hierarchy and use the template file it comes across first. So if you want to create a custom template for your 
acme_product custom post type, a good place to start is by copying the 
single.php file, saving it as 
single-acme_product.php and editing that.
However if you don’t want to create custom template files, WordPress will use the files already present in your theme, which would be 
archive.php and 
single.php and 
index.php files.
Single posts and their archives can be displayed using the 
single.php and 
archive.php template files respectively,
single posts of a custom post type will use single-{post_type}.php
and their archives will use archive-{post_type}.php
and if you don’t have this post type archive page you can pass BLOG_URL?post_type={post_type}
where 
{post_type} is the 
$post_type argument of the register_post_type() function.
So for the above example, you could create 
single-acme_product.php and 
archive-acme_product.php template files for single product posts and their archives.
Alternatively, you can use the 
is_post_type_archive() function in any template file to check if the query shows an archive page of a given post types(s), and the 
post_type_archive_title() to display the post type title.
Custom Post Type templates
single-{post-type}.php
The single post template used when a visitor requests a single post from a custom post type. For example, 
single-acme_product.php would be used for displaying single posts from a custom post type named 
acme_product.
archive-{post-type}.php
The archive post type template is used when visitors request a custom post type archive. For example, 
archive-acme_product.php would be used for displaying an archive of posts from the custom post type named 
acme_product. The 
archive.php template file is used if the 
archive-{post-type}.php is not present.
index.php
The 
index.php is used if a specific query template (
single-{post-type}.php, single.php, archive-{post-type}.php, archive.php, search.php) for the custom post type is not present.
Function Reference
register_post_type() : Registers a post type.
is_post_type_archive() : Checks if the query for an existing post type archive page.
post_type_archive_title() : Display or retrieve title for a post type archive.

Page Templates
Page templates are a specific type of template file that can be applied to a specific page or groups of pages.
As of WordPress 4.7 page templates support all post types. For more details how to set a page template to specific post types see example below.
Since a page template is a specific type of template file, here are some distinguishing features of page templates:
Page templates are used to change the look and feel of a page.
A page template can be applied to a single page, a page section, or a class of pages.
Page templates generally have a high level of specificity, targeting an individual page or group of pages. For example, a page template named 
page-about.php is more specific than the template files 
page.php or 
index.php as it will only affect a page with the slug of “about.”
If a page template has a template name, WordPress users editing the page have control over what template will be used to render the page.
Uses for Page Templates
Page templates display your site’s dynamic content on a page, e.g., posts, news updates, calendar events, media files, etc. You may decide that you want your homepage to look a specific way, that is quite different to other parts of your site. Or, you may want to display a featured image that links to a post on one part of the page, have a list of latest posts elsewhere, and use a custom navigation. You can use page templates to achieve these things.
This section shows you how to build page templates that can be selected by your users through their admin screens.
For example, you can build page templates for:
full-width, one-column
two-column with a sidebar on the right
two-column with a sidebar on the left
three-column
Page Templates within the Template Hierarchy
When a person browses to your website, WordPress selects which template to use for rendering that page. As we learned earlier in the Template Hierarchy, WordPress looks for template files in the following order:
Page Template — If the page has a custom template assigned, WordPress looks for that file and, if found, uses it.
page-{slug}.php — If no custom template has been assigned, WordPress looks for and uses a specialized template that contains the page’s slug.
page-{id}.php — If a specialized template that includes the page’s slug is not found, WordPress looks for and uses a specialized template named with the page’s ID.
page.php — If a specialized template that includes the page’s ID is not found, WordPress looks for and uses the theme’s default page template.
singular.php — If 
page.php is not found, WordPress looks for and uses the theme’s template used for a single post, irregardless of post type.
index.php — If no specific page templates are assigned or found, WordPress defaults back to using the theme’s index file to render pages.
There is also a WordPress-defined template named 
paged.php. It is not used for the page post-type but rather for displaying multiple pages of archives.
Page Templates Purpose & User Control
If you plan on making a custom page template for your theme, you should decide a couple of things before proceeding:
Whether the page template will be for one specific page or for any page; and
What type of user control you want available for the template.
Every page template that has a template name can be selected by a user when they create or edit a page. The list of available templates can be found at Pages > Add New > Attributes > Template. Therefore, a WordPress user can choose any page template with a template name, which might not be your intention.
For example, if you want to have a specific template for your “About” page, it might not be appropriate to name that page template “About Template” as it would be globally available to all pages (i.e. the user could apply it to any page). Instead, create a single use template and WordPress will render the page with the appropriate template, whenever a user visits the “About” page.
Conversely, many themes include the ability to choose how many columns a page will have. Each of these options is a page template that is available globally. To give your WordPress users this global option, you will need to create page templates for each option and give each a template name.
Dictating whether a template is for global use vs. singular use is achieved by the way the file is named and whether or not is has a specific comment.
Sometimes it is appropriate to have a template globally available even if it appears to be a single use case. When you’re creating themes for release, it can be hard to predict what a user will name their pages. Portfolio pages are a great example as not every WordPress user will name their portfolio the same thing or have the same page ID and yet they may want to use that template.
File Organization of Page Templates
As discussed in Organizing Theme Files, WordPress can recognize page templates stored in the theme’s root folder or in a first-level subdirectory of the theme folder.
The 
page-templates/ folder is a common convention for organizing global page templates, but it is not required. Page templates can also be stored in other first-level subdirectories, such as 
templates/ or 
page_templates/.
Nested subdirectories, such as 
pages/templates/, are not supported for page templates.
Note: A specialized page template file, meaning one created for a single specific page, cannot be stored in a subfolder. If you are using a Child Theme, the specialized page template also cannot be stored in the parent theme’s folder.
Creating Custom Page Templates for Global Use
Sometimes you’ll want a template that can be used globally by any page, or by multiple pages.  Some developers will group their templates with a filename prefix, such as 
page_two-columns.php
Important! Do not use 
page- as a prefix, as WordPress will interpret the file as a specialized template, meant to apply to only one page on your site.
For information on theme file-naming conventions and filenames you cannot use, see reserved theme filenames.
A quick, safe method for creating a new page template is to make a copy of 
page.php and give the new file a distinct filename. That way, you start off with the HTML structure of your other pages and you can edit the new file as needed.
To create a global template, write an opening PHP comment at the top of the file that states the template’s name.
<?php /* Template Name: Example Template */ ?>
It’s a good idea to choose a name that describes what the template does as the name is visible to WordPress users when they are editing the page. For example, you could name your template Homepage, Blog, or Portfolio.
This example from the TwentyFourteen theme creates a page template called Full Width Page:
<?php
/**
* Template Name: Full Width Page
*
* @package WordPress
* @subpackage Twenty_Fourteen
* @since Twenty Fourteen 1.0
*/
Once you upload the file to your theme’s folder (e.g., page-templates), go to the Page > Edit screen in your admin dashboard.
On the right hand side under attributesyou’ll see template.  This is where users are able to access your global page templates.
The select list has a maximum width of 250px, so longer names may be cut off.
Creating a Custom Page Template for One Specific Page
As mentioned in the Template Hierarchy page, you can create a template for a specific page.  To create a template for one specific page, copy your existing 
page.php file and rename it with your page’s slug or ID:
page-{slug}.php
page-{ID}.php
For example: Your About page has a slug of ‘about’ and an ID of 6. If your active theme’s folder has a file named 
page-about.php or 
page-6.php, then WordPress will automatically find and use that file to render the About page.
To be used, specialized page templates must be in your theme’s folder (i.e. /wp-content/themes/my-theme-name/ ).
Creating page templates for specific post types
By default, a custom page template will be available to the “page” post type.
To create a page template to specific post types, add a line under the template name with the post types you would like the template to support.
Example:
<?php
/*
Template Name: Full-width layout
Template Post Type: post, page, event
*/
// Page code here...
This ability to add page templates to post types other than “page” post type is supported only from WordPress 4.7
When at least one template exists for a post type, the ‘Post Attributes’ meta box will be displayed in the back end, without the need to add post type support for ‘page-attributes’ or anything else. The ‘Post Attributes’ label can be customzied per post type using the ‘attributes’ label when registering a post type.
Backward Compatibility:
Let’s say you want to publicly release a theme with support for post type templates. WordPress versions before 4.7 will ignore the Template Post Type header and show the template in the list of page templates, even though it only works for regular posts. To prevent that, you can hook into the theme_page_templates filter to exclude it from the list. Here’s an example:
/**
 * Hides the custom post template for pages on WordPress 4.6 and older
 *
 * @param array $post_templates Array of page templates. Keys are filenames, values are translated names.
 * @return array Filtered array of page templates.
 */
function makewp_exclude_page_templates( $post_templates ) {
	if ( version_compare( $GLOBALS['wp_version'], '4.7', '&lt;' ) ) {
		unset( $post_templates['templates/my-full-width-post-template.php'] );
	}
	return $post_templates;
}
add_filter( 'theme_page_templates', 'makewp_exclude_page_templates' );
That way you can support custom post type templates in WordPress 4.7 and beyond while maintaining full backward compatibility.
Note that theme_page_templates is actually a dynamic theme_{$post_type}_templates filter. The dynamic portion of the hook name, $post_type, refers to the post type supported by the templates. E.g. you can hook into theme_product_templates to filter the list of templates for the product post type.
Using Conditional Tags in Page Templates
You can make smaller, page-specific changes with Conditional Tags in your theme’s 
page.php file. For instance, the below example code loads the file 
header-home.php for your front page, but loads another file (
header-about.php) for your About page, and then applies the default 
header.php for all other pages.
if ( is_front_page() ) :
	get_header( 'home' );
elseif ( is_page( 'About' ) ) :
	get_header( 'about' );
else:
	get_header();
endif;
You can learn more about Conditional Tags here.
Identifying a Page Template
If your template uses the 
body_class() function, WordPress will print classes in the 
body tag for the post type class name (
page), the page’s ID (
page-id-{ID}), and the page template used. For the default 
page.php, the class name generated is 
page-template-default:
<body class="page page-id-6 page-template-default">
A specialized template (
page-{slug}.php or 
page-{ID}.php) also gets the 
page-template-default class rather than its own body class.
When using a custom page template, the class 
page-template will print, along with a class naming the specific template. For example, if your custom page template file is named as follows:
<?php
/* Template Name: My Custom Page */
?>
Then then rendered HTML generated will be as follows:
<body class="page page-id-6 page-template page-template-my-custom-page-php">
Notice the 
page-template-my-custom-page-php class that is applied to the 
body tag.
Page Template Functions
These built-in WordPress functions and methods can help you work with page templates:
get_page_template() returns the path of the page template used to render the page.
wp_get_theme()->get_page_templates() returns all custom page templates available to the currently active theme (
get_page_templates() is a method of the 
WP_Theme class).
is_page_template() returns true or false depending on whether a custom page template was used to render the page.
get_page_template_slug() returns the value of custom field 
_wp_page_template (
null when the value is empty or “default”).If a page has been assigned a custom template, the filename of that template is stored as the value of a custom field named 
'_wp_page_template' (in the 
wp_postmeta database table). (Custom fields starting with an underscore do not display in the edit screen’s custom fields module.)

Partial and Miscellaneous Template Files
Introduction
Not all template files generate the entire content that will be rendered by the browser. Some template files are pulled in by other template files such as 
comments.php, 
header.php, 
footer.php, 
sidebar.php and 
content-{$slug}.php. You’ll walk through each of these template files to get an understanding of the purpose and how to build them.
Header.php
The 
header.php file does exactly what you would expect.  It contains all the code that the browser will render for the header. This is a partial template file because unless a different template file calls the template tag, 
get_header(), the browser will not render the contents of this file.
Often sites have the same header regardless of the page or post you’re on.  However, some sites have slight variations such as a secondary navigation or different banner image depending on the page. Your 
header.php file can handle all these variations if you use conditional tags.
Almost all themes have a 
header.php file as the functionality and maintainability of this file pretty much demands its creation.
Below is an example of a header.php found in the twenty fifteen theme.
<!DOCTYPE html>
<html <?php language_attributes(); ?> class="no-js">
<head>
    <meta charset="<?php bloginfo( 'charset' ); ?>">
    <meta name="viewport" content="width=device-width">
    <link rel="profile" href="http://gmpg.org/xfn/11">
    <link rel="pingback" href="<?php bloginfo( 'pingback_url' ); ?>">
    <!--[if lt IE 9]>
    <script src="<?php echo esc_url( get_template_directory_uri() ); ?>/js/html5.js"></script>
    <![endif]-->
    <?php wp_head(); ?>
</head>
 
<body <?php body_class(); ?>>
    <div id="page" class="hfeed site">
        <a class="skip-link screen-reader-text" href="#content"><?php _e( 'Skip to content', 'twentyfifteen' ); ?></a>
        <div id="sidebar" class="sidebar">
            <header id="masthead" class="site-header" role="banner">
                <div class="site-branding">
                    <?php if ( is_front_page() && is_home() ) : ?>
                    <h1 class="site-title">
                        <a href="<?php echo esc_url( home_url( '/' ) ); ?>" rel="home"><?php bloginfo( 'name' ); ?></a>
                    </h1>
                    <?php else : ?>
                    <a href="<?php echo esc_url( home_url( '/' ) ); ?>" rel="home"><?php bloginfo( 'name' ); ?></a>
                    <?php endif;
                    $description = get_bloginfo( 'description', 'display' );
                    if ( $description || is_customize_preview() ) :
                        echo $description;
                    endif; ?>
                    <button class="secondary-toggle"><?php _e( 'Menu and widgets', 'twentyfifteen' ); ?></button>
                </div><!-- .site-branding -->
            </header><!-- .site-header -->
            <?php get_sidebar(); ?>
        </div><!-- .sidebar -->
        <div id="content" class="site-content">
Some of the code may look a little daunting at first, but if we break it down, it becomes simple enough. After the opening commment, the 
head is created. The template tag 
wp_head() pulls in all of our styles and any scripts that would appear in the head rather than the footer that we enqueued in our 
functions.php file.
Next, the 
body is opened and a mix of HTML and PHP are present. You can see some conditional tags in the site branding div that tweak a little bit of what is shown based on the page the user is on. Then the site navigation is pulled in. Lastly, the main site-content div is opened which will be closed most likely in the 
footer.php file.
One important template tag to note is 
body_class() found in the opening 
body tag. This is a super handy tag that makes styling your theme a lot easier by giving your body classes depending on the template file and other settings being used.
Footer.php
Much like the 
header.php file the 
footer.php is a very common template file that most themes utilize. The code in the 
footer.php file will not be rendered unless another template file pulls in the 
footer.php with 
get_footer() template tag.  Similarly to headers, you can make variations of footers using conditional tags.
Often developers will put widgetized areas in the footer so that the end user can easily drop and drag different content types into the footer.
Here is an example of a 
footer.php file from the Twenty Fifteen theme.
</div><!-- .site-content -->
<footer id="colophon" class="site-footer" role="contentinfo">
	<div class="site-info">
		<?php
		/**
		 * Fires before the Twenty Fifteen footer text for footer customization.
		 *
		 * @since Twenty Fifteen 1.0
		 */
		do_action( 'twentyfifteen_credits' );
		?>
		<a href="<?php echo esc_url( __( 'https://wordpress.org/', 'twentyfifteen' ) ); ?>"><?php printf( __( 'Proudly powered by %s', 'twentyfifteen' ), 'WordPress' ); ?></a>
	</div><!-- .site-info -->
</footer><!-- .site-footer -->
</div><!-- .site -->
<?php wp_footer(); ?>
</body>
</html>
404.php
When users try to visit a page on your website that doesn’t exist they’ll be directed to your 
index.php page unless you’ve created a 404.php template.  It’s a good idea to have some sort of message that the explains the page is missing or no longer available.  Creating this template helps keep the visual aspects of your theme consistent and provides your end users with helpful information.
Here is an example of a 404.php template file from the twenty fifteen theme.
<?php get_header(); ?>
<div id="primary" class="content-area">
	<main id="main" class="site-main" role="main">
		<section class="error-404 not-found">
			<header class="page-header">
				<h1 class="page-title"><?php _e( 'Oops! That page can’t be found.', 'twentyfifteen' ); ?></h1>
			</header><!-- .page-header -->
			<div class="page-content">
				<?php _e( 'It looks like nothing was found at this location. Maybe try a search?', 'twentyfifteen' ); ?>
				<?php get_search_form(); ?>
			</div><!-- .page-content -->
		</section><!-- .error-404 -->
	</main><!-- .site-main -->
</div><!-- .content-area -->
<?php get_footer(); ?>
Comments.php
The 
comments.php file handles exactly what you would expect, comments. This is a partial template that is pulled into other template files to display comments that users leave on a page or post. Several different pages and posts show comments so it makes sense to have one file that can be pulled in when needed.
The code involved in creating comments is expanded upon on the comment template page.
Sidebar.php
A lot of themes utilize sidebars to display widgets.  For a sidebar to work in a theme it must be registered and then a template file for the sidebar must be created.  You’ll learn more about registering sidebars in a later chapter. Sidebar files often have conditional statements and the 
is_active_sidebar( 'sidebar-name' ) function in them to ensure a widget is in use within the sidebar so that empty HTML isn’t added to a page unnecessarily.
Here is an example of a sidebar template file from the twenty fifteen theme. Notice at the bottom the sidebar is pulled in using 
<?php dynamic_sidebar( 'sidebar-1' ); >. Now whatever, widgets are put into that sidebar will display on the page that is using this pulling in this template.
<?php if ( has_nav_menu( 'primary' ) || has_nav_menu( 'social' ) || is_active_sidebar( 'sidebar-1' ) ) : ?>
	<div id="secondary" class="secondary">
		<?php if ( is_active_sidebar( 'sidebar-1' ) ) : ?>
			<div id="widget-area" class="widget-area" role="complementary">
				<?php dynamic_sidebar( 'sidebar-1' ); ?>
			</div><!-- .widget-area -->
		<?php endif; ?>
	</div><!-- .secondary -->
<?php endif; ?>
Content-{$slug}.php
Many theme developers break their template files into small bite sized pieces.  They’ll often put wrappers and page architecture elements in template files like 
page.php, home.php, comments.php etc but then they put the code displaying the content of those pages in another template file. Enter 
content-{$slug}.php: common examples would be 
content-page.php, content-post.php, content-portfolio.php, content-none.php.  These are not file names that WordPress recognizes and will interpret a certain way, rather they are a common approach to display specific types of content.
For example, often on blog posts you want to display the author’s name, the date of the post, and possibly the category of the post.  You’d also likely have links to previous and next posts. That information wouldn’t be appropriate on a regular page. Similarly on a portfolio page you would likely have a featured image or gallery you would want to display in a way differently than say a blog post’s or page’s featured images.
You’ll want to use the 
get_template_part() template tag to pull in the 
content-{$slug}.php file. To pull in your 
content-page.php file you would call 
get_template_part( 'content', 'page' );
Here is twenty fifteen’s example of a 
content-page.php template file.
<article id="post-<?php the_ID(); ?>" <?php post_class(); ?>>
	<header class="entry-header">
		<?php the_title( '<h1 class="entry-title">', '</h1>' ); ?>
	</header><!-- .entry-header -->
	<div class="entry-content">
		<?php the_content(); ?>
		<?php
		wp_link_pages( array(
			'before'      => '<div class="page-links"><span class="page-links-title">' . __( 'Pages:', 'twentyfifteen' ) . '</span>',
			'after'       => '</div>',
			'link_before' => '<span>',
			'link_after'  => '</span>',
			'pagelink'    => '<span class="screen-reader-text">' . __( 'Page', 'twentyfifteen' ) . ' </span>%',
			'separator'   => '<span class="screen-reader-text">, </span>',
		) );
		?>
	</div><!-- .entry-content -->
	<?php edit_post_link( __( 'Edit', 'twentyfifteen' ), '<footer class="entry-footer"><span class="edit-link">', '</span></footer><!-- .entry-footer -->' ); ?>
</article><!-- #post-## -->

Post Template Files
There are many template files that WordPress uses to display the Post post type. Any content dealing with a blog or its posts are within the Post post type.
Index.php
index.php will display Post post types if there is no other template file in place. As stated in many places, every theme must have an 
index.php file to be valid. Many basic themes can get away with just using the 
index.php to display their Post post types, but the use cases given above would justify creating other template files.
Often you will want unique content structure or layout depending on what is being displayed. There are many templates you can use to customize content structure based on the context within the site. The two most notable post template files are 
home.php and 
single.php which display a feed of posts and a single post respectively.
Home.php
When a static front page is used and the site has a page defined for the blog list the 
home.php file is used for the designated blog list page. Use of this template is encouraged over creating a custom page template because blog pagination on a custom page template will not work properly. If there is no 
home.php in the theme 
index.php will be used instead.
Single.php
It’s good sense to build as simply as possible in your template structure and not make more templates unless you have real need for them. Therefore, most theme developers don’t create a single-post.php file because single.php is specific enough. For the most part, all themes should have a 
single.php. Below is an example of a 
single.php file from the theme Twenty Fifteen.
<?php /**
 * The template for displaying all single posts and attachments
 *
 * @package WordPress
 * @subpackage Twenty_Fifteen
 * @since Twenty Fifteen 1.0
 */
 
get_header(); ?>
<div id="primary" class="content-area">
    <main id="main" class="site-main" role="main">
    <?php
    // Start the loop.
    while ( have_posts() ) : the_post();
        /*
         * Include the post format-specific template for the content. If you want to
         * use this in a child theme, then include a file called called content-___.php
         * (where ___ is the post format) and that will be used instead.
         */
        get_template_part( 'content', get_post_format() );
        // If comments are open or we have at least one comment, load up the comment template.
        if ( comments_open() || get_comments_number() ) :
            comments_template();
        endif;
        // Previous/next post navigation.
        the_post_navigation( array(
            'next_text' => '<span class="meta-nav" aria-hidden="true">' . __( 'Next', 'twentyfifteen' ) . '</span> ' .
                '<span class="screen-reader-text">' . __( 'Next post:', 'twentyfifteen' ) . '</span> ' .
                '<span class="post-title">%title</span>',
            'prev_text' => '<span class="meta-nav" aria-hidden="true">' . __( 'Previous', 'twentyfifteen' ) . '</span> ' .
                '<span class="screen-reader-text">' . __( 'Previous post:', 'twentyfifteen' ) . '</span> ' .
                '<span class="post-title">%title</span>',
        ) );
    // End the loop.
    endwhile;
    ?>
    </main><!-- .site-main -->
</div><!-- .content-area -->
<?php get_footer(); ?>
In the code example above you can see the header is pulled in with 
get_header() then there are a two html tags. Next the Loop starts and the template tag 
get_template_part( 
'content'``, get_post_format()); pulls in the appropriate content by determining the post type with 
get_post_format(). Next, comments are pulled in with the template tag comments_template(). Then there is some pagination. Lastly, the content divs are closed and then footer is pulled in with 
get_footer().
Singular.php
WordPress Version 4.3 added 
singular.php that comes in the hierarchy after 
single.php for posts, 
page.php for pages, and the variations of each. This template follows the rules of is_singular() and is used for a single post, regardless of post type. Themes that used the same code for both of those files (or included one in the other) can now simplify down to the one template.
Archive.php
Unless a developer includes meta data with permalinks in their templates, the 
archive.php will not be used. Meta data is information tied to the post. For example the date something was posted on, the author, and any categories, tags, or taxonomies used for the post are all examples of meta data. When a visitor to a website clicks on the meta data, the 
archive.php will render any posts associated with that piece of meta data. For example, if a visitor clicks on the name of an author, the 
archive.php will display all posts by that author.
Commonly, the title of the page being displayed by 
archive.php will be the name of the meta data the user clicked on. So if the user clicked on the Author’s name, the page name displaying all the other author’s posts will be the Author’s name and frequently there might be an additional description about the meta data. Here is a code example from Twenty Fifteen on their 
archive.php file. This snippet is the only piece of code that makes the 
archive.php file different from a 
home.php or 
index.php file.
    <?php the_archive_title( '
', '' );
        the_archive_description( '', '' );
    ?>
```
```
Author.php and Date.php
Author.php and 
date.php are more specific archive type files. If you need a refresher check out where they fit within the template heirarchy. Generally, 
archive.php will suffice for most themes’ needs and you won’t need to create these templates.
Author.php
If you are building a theme designed for multiple authors, it might make sense to build an author.php template. In the 
author.php template you could provide more information about an author, their gravatar, pull in their social media sites, and then all posts written by them. This would be a step up from relying just on the 
archive.php file.
Additionally, you can build specific 
author.php files for individual author’s by using their author ID or nicename. For example, say John Doe is the head author for a site with many guest authors. You may want all the guest authors’ information to display with author.php but you might build a specific author page with more information for John Doe by creating 
author-johndoe.php or 
author-3.php if his author ID is 3.
Date.php
Similarly, if you are building a theme directed at magazine or news websites, a 
date.php file might make sense to build as these websites frequently organize their articles and posts by date or issue. Additionally, you could build a 
day.php, 
month.php, or 
year.php if you found enough justification for it.
Category.php, Tag.php, and Taxonomy.php
If you need a refresher on what categories, tags, & taxonomies are you can look at their page. Often you won’t need to build out these template files. However, in an example of building a theme for food bloggers, there are some use cases for building these specific templates. In a food blogger website, the categories could be Great Restaurants, Beautiful Food, Ethnic Cuisine, and Recipes.
You might want most of your blog posts to display the same way except for any blogs that are categorized as recipes, because all recipes have ingredients and instrucitons sections. Therefore, you may want to build a 
category-recipe.php file to display your recipe blog posts in a grid view with some of the important details about the recipe visible.
Additionally, perhaps chocolate is a really important tag for the theme you’re building. It might make sense to build a 
tag-chocolate.php file so that you can display a specialized banner image of chocolate.
Search.php
Most themes have a search.php file so it is clear to users that their query went through. It is common to have some sort of header identifying the query results such as this snippet found int twenty fifteen’s theme.
<header class="page-header">
<h1 class="page-title">
    <?php printf( __( 'Search Results for: %s', 'twentyfifteen' ), get_search_query() ); ?>
</h1>
</header><!-- .page-header -->
This code snippet pulls in the query that was searched with 
get_search_query(). Often 
search.php will only pull in the excerpt instead of the full content since the user is trying to determine if the article or page fits their search.

Taxonomy Templates
When a visitor clicks on a hyperlink to category, tag or custom taxonomy, WordPress displays a page of posts in reverse chronological order filtered by that taxonomy.
By default, this page is generated using the index.php template file. You can create optional template files to override and refine the index.php template files. This section explains how to use and create such templates.
Taxonomy Template Hierarchy
WordPress display posts in the order determined by the Template Hierarchy.
The category.php, tag.php, and taxonomy.php templates allow posts filtered by taxonomy to be treated differently from unfiltered posts or posts filtered by a different taxonomy. (Note: post refers to any post type – posts, pages, custom post types, etc.). These files let you target specific taxonomies or specific taxonomy terms. For example:
taxonomy-{taxonomy}-{term}.php
taxonomy-{taxonomy}.php
tag-{slug}.php
tag-{id}.php
category-{slug}.php
category-{ID}.php
So you could format all posts in an animal taxonomy named news on a page that looks different from posts filtered in other categories.
The archive.php template provides the most general form of control, providing a layout for all archives; that is, a page that displays a list of posts.
Category
For categories, WordPress looks for the category-{slug}.php file. If it doesn’t exist, WordPress then looks for a file for the next hierarchical level, category-{ID}.php, and so on. If WordPress fails to find any specialized templates or an archive.php template file, it reverts to the default behavior, using index.php.
The category hierarchy is listed below:
category-{slug}.php: For example, if the category’s slug is named “news,” WordPress would look for a file named category-news.php.
category-{ID}.php: For example, if the category’s ID is “6”, WordPress would look for a file named category-6.php.
category.php
archive.php
index.php
Tag
For tags, WordPress looks for the tag-{slug}.php file. If it doesn’t exist, WordPress then looks for a file for the next hierarchical level, tag-{ID}.php, and so on. If WordPress fails to find any specialized templates or an archive.php template file, it will revert to the default behavior, using index.php.
The tag hierarchy is listed below:
tag-{slug}.php: For example, if the tag’s slug is named “sometag,” WordPress would look for a file named tag-sometag.php.
tag-{id}.php: For example, if the tag’s ID were “6,” WordPress would look for a file named tag-6.php.
tag.php
archive.php
index.php
Custom Taxonomy
A custom taxonomy hierarchy works similarly to the categories and tags hierarchies described above. WordPress looks for the taxonomy-{taxonomy}-{term}.php file. If it doesn’t exist, WordPress then looks for a file for the next hierarchical level, taxonomy-{taxonomy}.php, and so on. If WordPress fails to find any specialized templates or an archive.php template file, it will revert to the default behavior, using index.php.
The hierarchy for a custom taxonomy is listed below:
taxonomy-{taxonomy}-{term}.php: For example, if the taxonomy is named “sometax,” and the taxonomy’s term is “someterm,” WordPress would look for a file named taxonomy-sometax-someterm.php.
taxonomy-{taxonomy}.php: For example, if the taxonomy is named “sometax,” WordPress would look for a file named taxonomy-sometax.php
taxonomy.php
archive.php
index.php
Creating Taxonomy Template Files
Now you’ve decided that you need to create custom designs for content based on taxonomies, where do you start?
Rather than starting from a blank file, it is good practice to copy the next file in the hierarchy, if it exists. If you’ve already created an archive.php, make a copy called category.php and modify that to suit your design needs. If you don’t have an archive.php file, use a copy of your theme’s index.php as a starting point.
Follow the same procedure if you are creating any taxonomy template file. Use a copy of your archive.php, category.php, tag.php, or index.php as a starting point.
Examples
Now that you’ve selected the template file in your theme’s directory that you need to modify, let’s look at some examples.
Adding Text to Category Pages
Static Text Above Posts
Suppose you want some static text displayed before the list of posts on your category page(s). “Static” is text that remains the same, no matter which posts are displayed below, and no matter which category is displayed.
Open your file and above The Loop section of your Template file, insert the following code:
<p>This is some text that will display at the top of the Category page.</p>
This text will only display on an archive page displaying posts in that category.
Different Text on Some Category Pages
What if you want to display different text based on the category page that the visitor is using? You could add default text to the main category.php file, and create special category-{slug}.php files each with their own version of the text, but this would create lots of files in your theme. Instead, you can use conditional tags.
Again, this code would be added before the loop:
<?php if ( is_category( 'Category A' ) ) : ?>
	<p>This is the text to describe category A.</p>
<?php elseif ( is_category( 'Category B' ) ) : ?>
	<p>This is the text to describe category B.</p>
<?php else : ?>
	<p>This is some generic text to describe all other category pages, I could be left blank.</p>
<?php endif; ?>
This code does the following:
Checks to see if the visitor has requested Category A. If yes, it displays the first piece of text.
Checks for category B if the user didn’t request category A. If yes, it displays the second piece of text.
Displays the default text, if neither was requested.
Display Text only on First Page of Archive
If you have more posts than fits on one page of your archive, the category splits into multiple pages. Perhaps you want to display static text, if the user is on the first page of the results.
To do this, use a PHP if statement that looks at the value of the $paged WordPress variable.
Put the following above The Loop:
<?php if ( $paged < 2 ) : ?>
	<p>Text for first page of Category archive.</p>
<?php endif; ?>
This code asks whether the page displayed is the first page of the archive. If it is, the text for the first page is displayed. Otherwise, the text for the subsequent pages is displayed.
Modify How Posts are Displayed
Excerpts vs. Full Posts
You can choose whether to display full posts or just excerpts. By displaying excerpts, you shorten the length of your archive page.
Open your file and find the loop. Look for:
the_content()
And replace it with:
the_excerpt()
And if your theme is displaying excerpts but you want to display the full content, replace 
the_excerpt with 
the_content.

Comment Template
WordPress displays comments in your theme based on the settings and code in the 
comments.php file within your WordPress theme.
Simple comments loop
// Get only the approved comments
$args = array(
	'status' => 'approve',
);
// The comment Query
$comments_query = new WP_Comment_Query();
$comments       = $comments_query->query( $args );
// Comment Loop
if ( $comments ) {
	foreach ( $comments as $comment ) {
		echo '<p>' . $comment->comment_content . '</p>';
	}
} else {
	echo 'No comments found.';
}
The 
comments.php template contains all the logic needed to pull comments out of the database and display them in your theme.
Before we explore the template file you’ll want to know how to pull in the partial template file on the appropriate pages such as 
single.php. You’ll wrap the comment template tag in a conditional statement so comments.php is only pulled in if it makes sense to do.
// If comments are open or we have at least one comment, load up the comment template.
if ( comments_open() || get_comments_number() ) :
	comments_template();
endif;
Another comments.php Example
Here’s an example of the 
comments.php template included with the Twenty Thirteen theme:
<?php
/**
 * The template for displaying Comments.
 *
 * The area of the page that contains comments and the comment form.
 *
 * @package WordPress
 * @subpackage Twenty_Thirteen
 * @since Twenty Thirteen 1.0
 */
/*
 * If the current post is protected by a password and the visitor has not yet
 * entered the password we will return early without loading the comments.
 */
if ( post_password_required() ) {
	return;
}
?>
<div id="comments" class="comments-area">
	<?php if ( have_comments() ) : ?>
		<h2 class="comments-title">
			<?php
			printf(
				_nx(
					'One thought on "%2$s"',
					'%1$s thoughts on "%2$s"',
					get_comments_number(),
					'comments title',
					'twentythirteen'
				),
				number_format_i18n( get_comments_number() ),
				'<span>' . get_the_title() . '</span>'
			);
			?>
		</h2>
		<ol class="comment-list">
			<?php
			wp_list_comments( array(
				'style'       => 'ol',
				'short_ping'  => true,
				'avatar_size' => 74,
			) );
			?>
		</ol><!-- .comment-list -->
		<?php if ( get_comment_pages_count() > 1 && get_option( 'page_comments' ) ) : ?>
			<nav class="navigation comment-navigation" role="navigation">
				<h1 class="screen-reader-text section-heading"><?php _e( 'Comment navigation', 'twentythirteen' ); ?></h1>
				<div class="nav-previous"><?php previous_comments_link( __( '&larr; Older Comments', 'twentythirteen' ) ); ?></div>
				<div class="nav-next"><?php next_comments_link( __( 'Newer Comments &rarr;', 'twentythirteen' ) ); ?></div>
			</nav><!-- .comment-navigation -->
		<?php endif; // Check for comment navigation ?>
		<?php if ( ! comments_open() && get_comments_number() ) : ?>
			<p class="no-comments"><?php _e( 'Comments are closed.', 'twentythirteen' ); ?></p>
		<?php endif; ?>
	<?php endif; // have_comments() ?>
	<?php comment_form(); ?>
</div><!-- #comments -->
Breaking down the comments.php
The above 
comments.php can be broken down to the below parts for better understanding.
Template Header
Comments Title
Comment Listing
Comment Pagination
Comments are closed message.
The End
Template Header
This template begins by identifying the template.
<?php
/**
 * The template for displaying Comments.
 *
 * The area of the page that contains comments and the comment form.
 *
 * @package WordPress
 * @subpackage Twenty_Thirteen
 * @since Twenty Thirteen 1.0
 */
Next, there’s a test to see if the post is password protected and, if so, it stops processing the template.
/*
 * If the current post is protected by a password and the visitor has not yet
 * entered the password we will return early without loading the comments.
 */
if ( post_password_required() )
 return;
?>
Finally, there’s a test to see if there are comments associated with this post.
<div id="comments" class="comments-area">
	<?php if ( have_comments() ) : ?>
Comments Title
Prints out the header that appears above the comments.
Uses the _nx() translation function so other developers can provide alternative language translations.
<h2 class="comments-title">
	<?php
	printf(
		_nx(
			'One thought on "%2$s"',
			'%1$s thoughts on "%2$s"',
			get_comments_number(),
			'comments title',
			'twentythirteen'
		),
		number_format_i18n( get_comments_number() ),
		'<span>' . get_the_title() . '</span>'
	);
	?>
</h2>
Comment Listing
The following snippet creates an ordered listing of comments using the wp_list_comments() function.
<ol class="comment-list">
	<?php
	wp_list_comments( array(
		'style'       => 'ol',
		'short_ping'  => true,
		'avatar_size' => 74,
	) );
	?>
</ol><!-- .comment-list -->
Comment Pagination
Checks to see if there are enough comments to merit adding comment navigation and, if so, create comment navigation.
<?php if ( get_comment_pages_count() > 1 && get_option( 'page_comments' ) ) : ?>
	<nav class="navigation comment-navigation" role="navigation">
		<h3 class="screen-reader-text section-heading"><?php _e( 'Comment navigation', 'twentythirteen' ); ?></h3>
		<div class="nav-previous"><?php previous_comments_link( __( '&larr; Older Comments', 'twentythirteen' ) ); ?></div>
		<div class="nav-next"><?php next_comments_link( __( 'Newer Comments &rarr;', 'twentythirteen' ) ); ?></div>
	</nav><!-- .comment-navigation -->
<?php endif; // Check for comment navigation ?>
Comments are closed message.
If comments aren’t open, displays a line indicating that they’re closed.
<?php if ( ! comments_open() && get_comments_number() ) : ?>
	<p class="no-comments"><?php _e( 'Comments are closed.', 'twentythirteen' ); ?></p>
<?php endif; ?>
The End
This section ends the comments loop, includes the comment form, and closes the comment wrapper.
	<?php endif; // have_comments() ?>
	<?php comment_form(); ?>
</div><!-- #comments -->
Comments Pagination
If you have a lot of comments (which makes your page long), then there are a number of potential benefits to paginating your comments. Pagination helps improve page load speed, especially on mobile devices.
Enabling comments pagination is done in two steps.
Enable paged comments within WordPress by going to Settings > Discussion , and checking the box “Break comments into pages” . You can enter any number for the “top level comments per page”.
Open your 
comments.php template file and add the following line where you want the comment pagination to appear.
<div class="pagination">
	<?php paginate_comments_links(); ?>
</div>
Alternative Comment Template
On some occasions you may want display your comments differently within your theme. For this you would build an alternate file (ex. short-comments.php) and call it as follows:
<?php comments_template( '/short-comments.php' );
The path to the file used for an alternative comments template should be relative to the current theme root directory, and include any subfolders. So if the custom comments template is in a folder inside the theme, it may look like this when called:
<?php comments_template( '/custom-templates/alternative-comments.php' );
Function Reference
wp_list_comments() : Displays all comments for a post or Page based on a variety of parameters including ones set in the administration area.
comment_form() : This tag outputs a complete commenting form for use within a template.
comments_template() : Load the comment template specified in first argument
paginate_comments_links() : Create pagination links for the comments on the current post.
get_comments() : Retrieve the comments with possible use of arguments
get_approved_comments() : Retrieve the approved comments for post id provided.
Functions reference for retrieving comments meta
get_comment_link()
get_comment_author()
get_comment_date()
get_comment_time()
get_comment_text()

Custom Functionality (functions.php)
This document will introduce you to the 
functions.php file. It is one of the optional standard files you first learned about in Theme Structure. Both block and classic themes can utilize it.
The following will introduce you to the core concepts around using PHP within 
functions.php, but it will not teach you the PHP programming language itself. You can visit the official PHP documentation for more information on how to write your own PHP code.
Throughout the handbook, you will encounter more examples where you will add custom functionality, so getting the basics down is important. You can jump into more advanced PHP examples in the Features, Advanced Topics, and Classic Themes chapters.
What is functions.php?
The 
functions.php essentially acts like a WordPress plugin, letting you add custom PHP functions, classes, interfaces, and more. It opens up the entirety of the PHP programming language to your theme.
WordPress automatically loads the 
functions.php file (if it exists) as soon as it loads the theme on all page views on both the admin and front-end of the website. So it provides you with a lot of power to build unique features around WordPress.
Just because you can build plugin-like features in a theme doesn’t mean you always should, particularly if you are distributing your theme to others to use. If you are creating features that should be available regardless of the site’s design, it is best practice to put the code in a plugin. The rule of thumb is that themes should only deal with the site’s design.
While all themes can have a custom 
functions.php file, WordPress will only load the currently active theme’s.
The only caveat to that rule is when a child theme is active. In that case, WordPress loads the child theme’s 
functions.php just before loading the parent theme’s 
functions.php. You can learn more about child themes in the Advanced Topics chapter.
Common uses for functions.php
Because the 
functions.php file lets you write any PHP, you will often see themes with wildly different code, organizational systems, naming conventions, and more. The deeper your understanding of PHP, the easier it will be to follow the code from other themes.
The following are some uses you will often find in a theme’s 
functions.php file.
Adding actions or filters to hooks
Hooks are the entry point to extending WordPress’ functionality, providing you with a way to inject custom code or filter data. Think of them as a way for themes (and plugins) to communicate directly with WordPress.
WordPress’ hooks system offers two different methods for executing your code during the page loading process:
Action hooks allow you to run a custom action callback and “act on” the information that it receives.
Filter hooks let you filter data via a custom filter callback and manipulate it.
Technically, hooks are a part of the Plugin API, and you can read the documentation on them in the Plugin Handbook.
Despite being in the Plugin API, hooks are also extremely useful in the context of themes. Like plugins, you should always run your code on a hook so that it performs its functionality at the appropriate point in the load process.
Throughout this handbook, you will see examples of adding features or functionality from 
functions.php, and these examples will always use a hook. Familiarizing yourself with their documentation will make it easier to understand PHP code in the handbook.
Theme setup function
One common use case for many themes is adding a setup function, which is generally used to register theme-supported features with WordPress. This is almost always executed on the 
after_setup_theme action hook, which is the first hook available after a theme’s 
functions.php file has been loaded.
To test this, open your theme’s 
functions.php file (create one if it doesn’t exist), and add the following PHP code:
<?php
add_action( 'after_setup_theme', 'theme_slug_setup' );
function theme_slug_setup() {
	add_theme_support( 'wp-block-styles' );
}
This code adds support for WordPress’ more-opinionated block styles to your theme. You do not have to use this; it is merely serving as an example of what a setup function might look like.
Setup functions are more common in classic themes. When using a block theme, the theme is often automatically opted into the features needed. You can find a list of theme-supported features here:
Function Reference: 
add_theme_support()
Block Editor Handbook: Theme Support
Loading scripts and styles
If you are familiar with HTML, you will likely have come across adding JavaScript via the 
<script> tag or stylesheets via the 
<link rel=”stylesheet”/> or 
<style>  tags.
WordPress provides helper functions and specific action hooks for loading scripts and styles. This ensures that they are injected at the appropriate place in the document output. WordPress creates the appropriate HTML markup for you.
You can learn more about loading scripts and styles in the Including Assets documentation.
It is not uncommon when building block themes to have no need of including additional scripts/styles. Some themes rely entirely on Global Settings and Styles for the front-end design.
Including other PHP files
WordPress will automatically load your theme’s 
functions.php for you, but you are not limited to only adding custom PHP code in that file. You can load other files with PHP interfaces, classes, traits, and functions from elsewhere in your theme.
As you learned in Theme Structure, some themes include a custom folder named 
/inc (or any custom folder) to store custom PHP files. Let’s assume you had an 
/inc/helpers.php file for custom helper functions, you could load it via 
functions.php using the 
get_parent_theme_file_path() function:
include get_parent_theme_file_path( 'inc/helpers.php' );
Generally speaking, you should use this function to get the correct directory path to any PHP file you need to load.
Alternatively, if you wanted to allow a child theme to override the file with a fallback to the parent theme, you could use 
get_theme_file_path() instead:
include get_theme_file_path( 'inc/helpers.php' );
It’s not standard practice to let child theme’s override files with PHP functions or classes, but there are use cases where it’s needed.
Avoid closing ?> tags at the end of files
This section could otherwise be titled “How to avoid the dreaded WordPress white screen of death.”
There are various reasons that you might see a broken site with nothing but a white screen. One of those reasons is when the 
functions.php file (or any PHP file) has whitespace following its closing 
?> tag like this:
<?php
// some code...
?>
Many editor configurations will automatically add an extra line at the end of files (a common development practice). When you add a closing 
?> tag at the end of the file, it can be easy to miss this extra whitespace, which may cause the “white screen of death” in some environments.
The easiest way to avoid this issue is to leave the closing 
?> tag out altogether, which is perfectly valid PHP and standard practice. The above code should be written as:
<?php
// some code...

Global Settings and Styles
As you learned in Theme Structure, 
theme.json is a standard file that WordPress looks for in your theme. While it is not technically required for a block theme, it is almost always necessary to configure various settings and styles for your theme.
This documentation is a quick introduction on what 
theme.json is and how it works. However, it is such a massive topic that there is a dedicated chapter that explores everything you can do with it: Global Settings and Styles.
What is theme.json?
theme.json is a configuration file that tells WordPress what settings you want to enable, how to style specific elements and blocks, and which templates and template parts to register.
Some of the things you can do with 
theme.json are:
Enable or disable features like drop caps, padding, margin, and line-height.
Add a color palette, gradients, duotones, and shadows.
Configure typographical features like font families, sizes, and more.
Add CSS custom properties.
Register custom templates and assign parts to template part areas.
Your 
theme.json configuration will be reflected in what you see in places like the post, template, and site editors in the WordPress admin. Custom styles, in particular, will be reflected in the Styles interface:
theme.json structure
A 
theme.json file can be as little as a few lines of code, such as this example that enables the appearance tools for blocks:
{
	"$schema": "https://schemas.wp.org/trunk/theme.json",
	"version": 2,
	"settings": {
		"appearanceTools": true
	}
}
Or it can be a massively complex file that spans 1,000s of lines of code. How many of the features you want to configure is entirely up to you.
The starting point is understanding the top-level properties that can be configured. Here is an outline of what this looks like:
{
	"$schema": "https://schemas.wp.org/trunk/theme.json",
	"version": 2,
	"settings": {},
	"styles": {},
	"customTemplates": {},
	"templateParts": {},
	"patterns": []
}
Here are what each of these properties define:
$schema: Used for defining the supported JSON schema, which will integrate with many code editors to give you on-the-fly hints and error reporting.
version: The 
theme.json schema version you are building for. The latest version is 2 and can always be found in the 
theme.json Living Reference, a document that lists the most up-to-date properties you can set.
settings: Used to define your block controls and color palettes, font sizes, and more.
styles: Used to apply colors, font sizes, custom CSS, and more to the website and blocks.
customTemplates: Metadata for custom templates defined in your theme’s 
/templates folder.
templateParts: Metadata for template parts defined in your theme’s  
/parts folder.
patterns: An array of pattern slugs to be registered from the Pattern Directory.
You will learn more about these properties and their sub-properties in the Global Settings and Styles chapter.
Settings and styles hierarchy
The 
theme.json file in your theme is only one level in a hierarchy of setting and style configurations for a website. This means it can be overridden under certain circumstances.
The order of this hierarchy from lowest to highest is:
WordPress 
theme.json: WordPress has its own 
theme.json file that defines the default settings and styles.
Theme 
theme.json: Anything you define in your theme’s 
theme.json file overrides the WordPress defaults.
Child theme 
theme.json: If active, a child theme’s 
theme.json takes priority over the main or “parent” theme.
User configuration: Users can further customize how their site works under Appearance > Editor in the WordPress admin, and the JSON data is saved in their site’s database. Their choice takes priority over all other levels in the hierarchy.
There are also filter hooks available that let plugin and theme authors override the values dynamically. To learn more about these, check out How to modify theme.json data using server-side filters from the WordPress Developer Blog.
The important thing to remember is that anything configured in your 
theme.json file may not take priority in the hierarchy.

Including Assets
Many block themes do not need to load any assets. For design aspects, specifically, much of this can be handled through the Global Settings and Styles system. But there are times when you might need to include a CSS stylesheet, custom JavaScript file, or even other types of media.
If you are familiar with HTML, you might be accustomed to including CSS stylesheets via the 
<link rel=”stylesheet”/> or 
<style> tags. The same might be true for including JavaScript via the 
<script> tag. But you should never manually hard code these HTML elements in your theme.
WordPress has specific hooks for determining when to load scripts/styles and functions for generating the markup. This ensures that WordPress, any active plugins, and your theme all play nicely together.
In this document, you will learn the necessary functions for generating the proper URL to point to asset files and how to include scripts, styles, and other assets in your theme.
This documentation is a leap forward in comparison to some of the previous pages in the Core Concepts chapter. You will need some baseline PHP and HTML knowledge to follow along. You must also understand how to use your theme’s 
functions.php file. This is necessary for loading CSS stylesheet and JavaScript files.
URL and directory path functions
Before including assets, you should become familiar with some of the utility functions that WordPress provides for getting URLs and directory paths within a theme. You should always use these helper functions when including any type of asset to ensure the URL or path is correct.
Three of the primary URL helper functions are:
get_stylesheet_uri(): Returns the active theme’s 
style.css file URL.
get_theme_file_uri( $file ): Returns the active theme’s URL, with an optional 
$file parameter. Falls back to the parent theme if a child theme is active and the file doesn’t exist.
get_parent_theme_file_uri( $file ): Returns the parent theme’s URL, with an optional 
$file path.
For directory paths, which are needed less often for assets, there are two primary functions:
get_theme_file_path( $file ): Returns the active theme’s directory path, with an optional 
$file parameter. Falls back to the parent theme if a child theme is active and the file doesn’t exist.
get_parent_theme_file_path( $file ): Returns the parent theme’s directory path, with an optional 
$file parameter.
Including CSS
wp_enqueue_style() is the primary function for enqueueing a stylesheet, which tells WordPress that you want to put it in the queue to load. You would use this function within an action hook callback in your 
functions.php file, which you learned about in Custom Functionality. You’ll learn which action hooks to use for specific scenarios in the next sections.
Take a look at the function signature:
wp_enqueue_style( 
	string $handle, 
	string $src           = '', 
	string[] $deps        = array(), 
	string|bool|null $ver = false, 
	string $media         = 'all'
);
You can use these parameters:
$handle is a unique name/ID for the stylesheet and should be prefixed with your theme slug.
$src is the file URL of your stylesheet. While it is technically an optional parameter, it is required to actually load a specific stylesheet.
$deps is an optional array of other stylesheet handles that your stylesheet is dependent upon.
$ver sets the version number of your stylesheet and is used for cache busting. Defaults to the current WordPress version.
$media is for specifying which type of media to load this stylesheet for, such as 
all (default), 
screen, 
print, or 
handheld.
If you were enqueuing a stylesheet located at 
/assets/css/example.css in your theme, your function call might look like this:
wp_enqueue_style( 
	'theme-slug-example',
	get_parent_theme_file_uri( 'assets/css/example.css' ),
	array(),
	wp_get_theme()->get( 'Version' ),
	'all'
);
The above code uses 
wp_get_theme() to grab the theme’s version number for cache busting, but you can leave it at the default or use something custom altogether.
Front-end stylesheets
When loading stylesheets on the front end of a website, you will use the 
wp_enqueue_scripts hook for most scenarios.
Let’s assume that you wanted to load your theme’s 
style.css file using the 
get_stylesheet_uri() function. You would do this by adding the following code to your 
functions.php file:
add_action( 'wp_enqueue_scripts', 'theme_slug_enqueue_styles' );
function theme_slug_enqueue_styles() {
	wp_enqueue_style( 
		'theme-slug-style', 
		get_stylesheet_uri()
	);
}
Remember that you can also pass other parameters to the 
wp_enqueue_style() function if needed. The above code is the minimum needed to load the stylesheet.
Let’s further suppose that you wanted to load a second stylesheet located at 
/assets/css/primary.css in your theme. For this, you would use the 
get_parent_theme_file_uri() function to get the correct URL.
Here is what your code would look like with both stylesheets enqueued:
add_action( 'wp_enqueue_scripts', 'theme_slug_enqueue_styles' );
function theme_slug_enqueue_styles() {
	wp_enqueue_style(
		'theme-slug-style', 
		get_stylesheet_uri()
	);
	wp_enqueue_style( 
		'theme-slug-primary',
		get_parent_theme_file_uri( 'assets/css/primary.css' )
	);
}
Inline styles
There are times when you might need to add some inline CSS to the 
<head> area on the front end. WordPress has the 
wp_add_inline_style() function for this specific scenario.
Here is a look at the function signature:
wp_add_inline_style( 
	string $handle, 
	string $data 
);
In this case, you must pass in a 
$handle parameter that matches a handle of an existing stylesheet that is enqueued for the page. The 
$data parameter is your custom CSS code.
Let’s extend the code from the previous section by adding a small bit of CSS that sets the body background color to a light gray:
add_action( 'wp_enqueue_scripts', 'theme_slug_enqueue_styles' );
function theme_slug_enqueue_styles() {
	wp_enqueue_style(
		'theme-slug-style', 
		get_stylesheet_uri()
	);
	wp_enqueue_style( 
		'theme-slug-primary',
		get_parent_theme_file_uri( 'assets/css/primary.css' )
	);
	wp_add_inline_style( 
		'theme-slug-primary', 
		'body { background: #eee; }'
	);
}
In the 
wp_add_inline_style() function call, the code uses the existing 
theme-slug-primary handle to attach an inline style.
Editor stylesheets
When creating a theme with custom CSS on the front end, you will almost always want your custom styles to also appear in the editor. This will create a consistent user experience across the site. But WordPress does not automatically load your front-end stylesheets in the editor.
For that, you will need to use the 
add_editor_style() function:
add_editor_style( array|string $stylesheet = 'editor-style.css' );
It accepts a single parameter of 
$stylesheet, which can be a single stylesheet filename or an array of filenames. These can be relative to the theme folder or a full URL.
Note that when using relative URLs, a file in the child theme with the same filename will take priority. That’s why it’s generally best practice to use the full stylesheet URL.
This code snippet shows how to add the active theme’s main 
style.css file as an editor style:
add_action( 'after_setup_theme', 'theme_slug_setup' );
function theme_slug_setup() {
	add_editor_style( get_stylesheet_uri() );
}
If you wanted to add both the 
style.css file and 
primary.css from the earlier examples, you could pass them in as an array:
add_action( 'after_setup_theme', 'theme_slug_setup' );
function theme_slug_setup() {
	add_editor_style( array(
		get_stylesheet_uri(),
		get_parent_theme_file_uri( 'assets/css/primary.css' )
	) );
}
Block stylesheets
WordPress also includes a 
wp_enqueue_block_style() function for loading per-block stylesheets in the editor and on the front end. This is covered in full detail in the Block Stylesheets documentation.
For an advanced exploration of block stylesheets, read Leveraging theme.json and per-block styles for more performant themes on the WordPress Developer Blog.
Including JavaScript
Like stylesheets, WordPress has a primary function for enqueueing JavaScript files: 
wp_enqueue_script(). You would also use this function within an action hook callback in your 
functions.php file, and you’ll learn which hooks to use in the following sections.
Take a look at the function signature:
wp_enqueue_script( 
	string $handle, 
	string $src           = '', 
	string[] $deps        = array(), 
	string|bool|null $ver = false, 
	array|bool $in_footer = false
);
You can use these parameters:
$handle: A unique name/ID for the script and should be prefixed with your theme slug.
$src: The file URL of your script. While it is technically an optional parameter, it is required to actually load a specific script
$deps: An optional array of other script handles that your script is dependent upon.
$ver: Sets the version number of your script and is used for cache busting. Defaults to the current WordPress version.
$in_footer: Determines whether to load the script in the header or footer. As of WordPress 6.3, this parameter accepts an array of values:
strategy: Accepts either 
'defer' (default) or 
'async' to set the script-loading strategy.
in_footer: A boolean value to determine whether to load the script in the header or footer.
If you were enqueuing a script located at 
/assets/js/example.js in your theme, your function call might look like this:
wp_enqueue_script( 
	'theme-slug-example',
	get_parent_theme_file_uri( 'assets/js/example.js' ),
	array(),
	wp_get_theme()->get( 'Version' ),
	true
);
Front-end JavaScript
When loading stylesheets on the front end of a website, you will use the 
wp_enqueue_scripts hook for most scenarios.
Suppose you had a custom navigation script located at 
assets/js/navigations.js in your theme. For this, you would use the 
get_parent_theme_file_uri() function to get the correct URL.
Here is what your function would look like when enqueueing the script:
add_action( 'wp_enqueue_scripts', 'theme_slug_enqueue_scripts' );
function theme_slug_enqueue_scripts() {
	wp_enqueue_script( 
		'theme-slug-navigation',
		get_parent_theme_file_uri( 'assets/js/navigation.js' ),
		array(),
		wp_get_theme()->get( 'Version' ),
		true
	);
}
Inline JavaScript
Sometimes you might want to add some inline JavaScript to the 
<head> area on the front end. WordPress has the 
wp_add_inline_script() function for this purpose.
Take a look at the function signature:
wp_add_inline_script( 
	string $handle, 
	string $data, 
	string $position = 'after' 
);
Like its counterpart for styles, you must attach this to an enqueued script via the 
$handle parameter. The secondary parameter, 
$data, should be the JavaScript code itself. The difference here is the addition of a third parameter, 
$position, which lets you position the inline script before or after the script that it is attached to.
The following code builds on top of the navigation script from the previous section by adding an inline script to it:
add_action( 'wp_enqueue_scripts', 'theme_slug_enqueue_scripts' );
function theme_slug_enqueue_scripts() {
	wp_enqueue_script( 
		'theme-slug-navigation',
		get_parent_theme_file_uri( 'assets/js/navigation.js' ),
		array(),
		wp_get_theme()->get( 'Version' ),
		true
	);
	wp_add_inline_script( 
		'theme-slug-navigation', 
		'console.log( "Testing" );'
	);
}
In the 
wp_add_inline_script() function call, the code uses the existing 
theme-slug-navigation handle to attach the inline style.
Editor JavaScript
When you need to load a JavaScript file for the block editor, you must use the 
enqueue_block_editor_assets hook. Note that this is for loading scripts on the admin page itself and not within the content iframe.
Suppose you had an 
assets/js/editor.js file that you needed to load for the editor. Your code should look like this:
add_action( 'enqueue_block_editor_assets', 'theme_slug_enqueue_editor_scripts' );
function theme_slug_enqueue_editor_scripts() {
	wp_enqueue_script( 
		'theme-slug-editor',
		get_parent_theme_file_uri( 'assets/js/editor.js' ),
		array(),
		wp_get_theme()->get( 'Version' ),
		true
	);
}
Generally, themes wouldn’t need to load JavaScript for the editor itself. But for advanced use cases, it may be necessary. It is also recommended to integrate with the 
@wordpress/scripts package for easier management. For more information on how to do this, read Beyond block styles, part 1: using the WordPress scripts package with themes.
Default WordPress scripts
WordPress bundles many custom and third-party scripts. You should always use these scripts if you need one of them instead of loading a custom version. This ensures that you avoid conflicts with plugins.
Some of the scripts are referenced in the 
wp_enqueue_script() documentation, but that list may not always be up to date. You can find the full list of included files in wp-includes/script-loader.php.
Including images
Block themes will not often need to include images, except in patterns. You will learn more about these in the Block Patterns documentation. But for a quick overview, let’s take a look at how to reference an image in your theme.
Assuming you had an image file located at 
assets/img/example.webp, you would use this code to reference the correct URL:
<img src="<?php echo esc_url( get_parent_theme_file_uri( 'assets/img/example.webp' ) ); ?>" alt="" />
Note that the above example uses 
get_parent_theme_file_uri(). In most cases, this will be the correct function.
But if you are building a child theme or a theme where you would like to allow other child theme authors to override the image, you can use 
get_theme_file_uri() instead:
<img src="<?php echo esc_url( get_theme_file_uri( 'assets/img/example.webp' ) ); ?>" alt="" />
Including fonts
Typically, you would expect fonts to fall directly under the assets documentation. But WordPress has special methods for loading fonts via the 
theme.json file that integrates with the editor. This documentation is under the Typography page of the Global Settings and Styles chapter.

Main Stylesheet (style.css)
As described in Theme Structure, WordPress requires that all themes include a 
style.css file. Its most important function is to “register” the theme with WordPress through configuration data at the top of the file. Many themes also use it to serve CSS to the front-end (and even the editor).
In this document, you will learn how to configure your theme data via the 
style.css file header.
File Header
The 
style.css file header is used to configure data about the theme. WordPress uses this information to determine how some features work and displays some of this data under the Appearance > Themes screen for users.
Here is a look at what the theme details overlay looks like for the default Twenty Twenty-Three theme:
Most of that information is pulled directly from the 
style.css file header. It is one of the most vital parts of creating a WordPress theme.
When determining which themes are available to activate, WordPress searches through each folder under 
/wp-content/themes, looking for a 
style.css file. If one is found, it pulls the first 8kb of data from the file and determines if there is a file header with standard fields defined.
In themes, this is merely a CSS comment block with some standard keys and values defined.
Suppose you were creating a theme with the folder name of 
fabled-sunset. WordPress would look for your theme’s 
style.css in the following location:
wp-content/
themes/
fabled-sunset/
style.css
For WordPress to recognize your theme, you would at least need the 
Theme Name field defined at the top of 
style.css like so:
/**
 * Theme Name: Fabled Sunset
 */
This is the minimum required header field for a valid theme. Of course, you’ll want to add much more information about your theme.
Header fields
There are many supported fields, and you will likely use most of them in your themes. Here is a quick look at a theme’s 
style.css file header with each of the fields configured:
/**
 * Theme Name:        Fabled Sunset
 * Theme URI:         https://example.com/fabled-sunset
 * Description:       Custom theme description...
 * Version:           1.0.0
 * Author:            Your Name
 * Author URI:        https://example.com
 * Tags:              block-patterns, full-site-editing
 * Text Domain:       fabled-sunset
 * Domain Path:       /assets/lang
 * Tested up to:      6.4
 * Requires at least: 6.2
 * Requires PHP:      7.4
 * License:           GNU General Public License v2.0 or later
 * License URI:       https://www.gnu.org/licenses/gpl-2.0.html
 */
The following list outlines what each of these fields does.
While the 
Theme Name is the only field required to work with WordPress, you must also include some other fields when submitting a theme to the WordPress theme directory. These fields are marked with * below.
Theme Name*: A unique name for your theme.
Theme URI: The URL of a public web page where users can find more information about the theme.
Description*: A description of the theme, which will be displayed when viewing a theme’s details in the WordPress admin and other places. It is also used for themes submitted to the WordPress theme directory.
Version*: The version of the theme, written in 
X.X or 
X.X.X format.
Author*:  Your name or the name of the organization who developed the theme. For themes submitted to the theme directory, it is recommended to use the WordPress.org username.
Author URI: The URL of the individual or organization who created the theme.
Tags: A comma-separated list of features the theme supports. The Theme Review Handbook has a list of valid tags for submission to the theme directory, but third-party sites may use a different system.
Text Domain*: The string used for the textdomain for translations.
Domain Path: A relative path to where theme translations are stored. WordPress uses this field when the theme is disabled to detect translations. Defaults to 
/languages.
Tested up to*: The last WordPress version the theme has been tested up to, written in 
X.X format (e.g., 
6.4, 
6.2.1, etc.).
Requires at least*: The oldest WordPress version the theme will work with, written in 
X.X format (e.g., 
6.3, 
6.2.1, etc.).
Requires PHP*: The oldest PHP version the theme will work with, written in 
X.X format (e.g., 
8.0, 
7.4, etc.).
License*: The license for the theme.
License URI*: The URL of the theme’s license.
Child theme header fields
When building a child theme, there is one additional supported field: Template. This is used to designate the parent theme’s folder.
If the fictional “Fabled Sunset” theme listed above was the parent of your child theme named “Grand Sunrise,” your 
style.css header fields would look similar to this:
/**
 * Theme Name: Grand Sunrise
 * Template:   fabled-sunset
 * ...other header fields
 */
The 
Template field must match the parent theme’s folder name exactly (relative to the 
wp-content/themes directory) for this to work. Otherwise, WordPress will not be able to appropriately match them.
You can learn more about child themes in the Advanced Topics chapter.
Custom header fields
Some third-party marketplaces or systems may also make use of custom header fields. These are not officially supported by WordPress, but they are definitely allowed and should not negatively impact how the theme works within WordPress.
Custom CSS
The 
style.css file is not merely a configuration file. You can also use it to write custom CSS code to alter the design of your theme, assuming the file is properly loaded.
With block themes, most or all of the design is ideally handled through the 
theme.json file, which you will learn about in the Global Settings and Styles documentation.
But there are times when you will want or need to add custom CSS. You can learn more about this in the Including Assets documentation.

Templates
In block themes, templates are made up of a collection of blocks. You might have a Site Logo block sitting next to a Navigation block in the header area. You might put Social Icons in the footer above a copyright notice.
As you build out your own themes, you will get to decide how your templates come together. That’s at least half the fun of theming!
In this document, you will learn the basic terminology around templating in WordPress. Reading through this quick primer on the subject will provide you with some foundational knowledge moving forward. There is a dedicated Templates chapter that provides a full overview of working with templates.
What are templates?
Theme templates represent the markup of the webpage. They create the document structure and print both static data (e.g., paragraph text) and dynamic data (e.g., post content) to the front end of your site.
Let’s take a look at a template from the default Twenty Twenty-Three theme.
Go to Appearance > Editor > Templates > Single Posts in your WordPress admin. This will show you what a Single post template looks like:
Single post template of the default Twenty Twenty-Three theme.
As shown above, the template is made up of various blocks. Some of them are in placeholder states and will dynamically display content based on what page is being viewed on the front end of the site.
If you select the ⋮ (Options) button in the template editor and select the Code editor option, you will see the block markup of the template:
Code view of the default Twenty Twenty-Three theme’s single post template.
One of the great things about templating in WordPress is that you never really have to interact directly with template code. You have the visual Site Editor to make any and all customizations you want. But the code is there if you need it.
Ultimately, the template produces HTML markup on the front end like this (shortened for clarity):
<!DOCTYPE html>
<html lang="en-US">
<head>
	<title>Post Title</title>
	<!-- Scripts, styles, and meta here. -->
</head>
<body class="post-template single single-post">
	<div class="wp-site-blocks">
		<header class="wp-block-template-part">
			<!-- Header blocks here. -->
		</header>
		<main class="wp-block-group is-layout-flow wp-block-group-is-layout-flow">
			<!-- Nested blocks here. -->
		</main>
		<footer class="wp-block-template-part">
			<!-- Footer blocks here. -->
		</footer>
	</div>
</body>
</html>
WordPress automatically handles the final markup for you, so all you need to do is create the templates.
How the templating system works
Whenever you visit a page on the front end of your website, WordPress must determine which template file to load. In the example above, the Single post template (
single.html) is used to display the content of single blog posts.
But there are many other types of templates. For example, you might have a Page template (
page.html) for displaying the content of your site’s pages or an Author template (
author.html) for displaying post author archives.
WordPress uses the template hierarchy to determine which template file to load. It is essentially a set of rules that defines which template to use based on the web page being viewed. If a template doesn’t exist, WordPress will continue looking down through the hierarchy until it finds one that does.
If no specific template is found, it will fall back to the Index template: 
index.html. As you learned in Theme Structure, this is the minimum required template for a block theme to function.
The Templates chapter covers the hierarchy in full detail. There, you will learn which templates are loaded for each page of a WordPress site.
Template files
WordPress expects template files to be located under the 
/templates folder in your theme. A typical theme will have several templates, which would be organized like this:
templates/
404.html
archive.html
author.html
index.html (required)
page.html
single.html
search.html
These are some of the common templates you will find a theme:
index.html: The fallback template file. It is required in all themes.
404.html: The 404 template is used when WordPress cannot find a post, page, or other content that matches the visitor’s request.
archive.html: The archive template is used when visitors request posts by archive-type views like category, author, or date and a more-specific template is unavailable.
author.html: The author page template is used whenever a visitor loads an author archive.
category.html: The category template is used when visitors request posts by category.
page.html: The page template is used when visitors request individual pages.
search.html: The search results template is used to display a visitor’s search results.
single.html:  The single post template is used when a visitor requests a single post.
tag.html: The tag template is used when visitors request posts by tag.
This is not an exhaustive list. You will learn the ins and outs of every template file as you dive deeper into the Templates chapter. The goal for now is to give you a baseline understanding of what to expect.
Template parts
Template parts, or “parts” for short, are another integral part of the templating system in WordPress. As the name suggests, template parts are a “part” of a template.
A template may consist of none, one, or more parts.
The great thing about parts is they help you follow the DRY (Don’t Repeat Yourself) principle. By including parts in your templates, you avoid having to repeat building the same block code over and over.
On most websites, there are sections of the page that typically stay the same, regardless of the page that you are viewing. Can you think of any repeated sections that are common on websites?
The site header and footer are likely the most recognizable “parts” of a webpage, and they just so happen to be the most common template parts you’ll find in themes. While it’s not required to include them, they are de facto standards.
Go to Appearance > Editor > Patterns > Template Parts in your WordPress admin. Here is what the Header template part looks like from the default Twenty Twenty-Three theme:
Headers for the Twenty Twenty-Three theme.
WordPress looks for template parts in your theme’s 
/parts folder, which should be organized like this:
parts/
header.html
footer.html
Other common template parts are for the comments area and sidebars, but your theme can have as few or as many parts as you want.
You’ll learn more about how to register and create custom parts in the Template Parts documentation.

Theme Structure
In the Getting Started chapter, you learned the basics of what a theme is and how to get one up and running without code. A no-code approach is perfectly OK for simple themes, but once you want to add things that are not possible in the user interface, you’ll need to start working directly with code.
The first step of customizing theme code is to open the theme in your preferred file editor. You can use any theme for this, even the one you created from the Getting Started chapter.
It’s a good idea to familiarize yourself with what others are doing, so feel free to look at several block themes from the WordPress theme directory.
This document will walk you through what the file and folder structure will look like in a typical block theme.
Files and folders
WordPress themes are nothing more than a collection of various files that rely on different web technologies, such as HTML, CSS, and PHP. Block themes also follow a standard structure in how many of those files are laid out.
At its most basic, a theme’s structure will look similar to the following. Take note of the files/folders marked required because they are necessary for a block theme to work:
parts/
footer.html
header.html
patterns/
example.php
styles/
example.json
templates/
404.html
archive.html
index.html (required)
singular.html
README.txt
functions.php
screenshot.png
style.css (required)
theme.json
Required files
There are two necessary files for WordPress to recognize your block theme, and you will learn more about these in the coming documentation:
style.css (Main Stylesheet): This file is required for configuring theme data, such as its name and description. It can also be used for adding custom CSS.
templates/index.html (Templates): The default/fallback template. This is necessary for WordPress to consider this a block theme.
Optional files
A theme can include any number of custom files other than the required list above. WordPress also looks for a few other files and uses them if they are available:
README.txt (Theme Review: Files): This is not used directly by the WordPress software. But it is a required file when submitting a theme to the official WordPress theme directory, meant to provide information about the theme to users.
functions.php (Custom Functionality): A PHP file that WordPress automatically loads after the theme is initialized during the page-loading process. You can use it to run custom PHP.
screenshot.png: A 1200×900 screenshot image of your theme. Used for displaying your theme under Appearance > Themes in the WordPress admin and in the WordPress theme directory (if submitted there). Both 
.png and 
.jpg are acceptable file formats.
theme.json (Global Settings and Styles): Used to configure settings and styles for the site, integrating with the user interface.
Standard folders
In the example above, there were a few folders included. A theme can have many more folders, but WordPress has designated a few of them for specific features. You will learn more about these folders as you read through this chapter:
parts (Template Parts): Houses custom template parts for your theme. Parts are smaller sections that you can include within top-level templates. Often, this will include things like headers, footers, and sidebars.
patterns (Block Patterns): Reusable patterns made up of one or more blocks that users can insert via the editor interface. WordPress will automatically register files included in this folder.
styles (Style Variations): Variations on the theme’s global settings and styles stored in individual JSON files.
templates (Templates): Files that represent the overall document structure of the front-end. Templates are made up of block markup and are what site visitors see.
Advanced theme structure
This section is meant to familiarize you with some of the common files you’ll see in themes but not to cover every possibility in detail. These files are entirely optional and will differ from theme to theme. You may skip this section for now if you are not comfortable with more advanced development methods.
In reality, block themes can contain many more files and folders. The more complex the project becomes, the more complex its structure will be.
Let’s add a few extra files and folders to the original example:
assets/
css/
core-site-title.css
images/
header-background.png
js/
navigation.js
inc/
ClassName.php
functions-helpers.php
parts/
footer.html
header.html
patterns/
example.php
styles/
example.json
templates/
404.html
archive.html
index.html (required)
singular.html
.editorconfig
.gitattributes
.gitignore
CHANGELOG.md
LICENSE.md
README.txt
functions.php
package.json
screenshot.png
style.css (required)
theme.json
Optional folders
There is no limit on what folders may be included, but the above example added two of the most common use cases you’ll come across in WordPress themes:
assets (Including Assets): Many theme authors use this folder to store additional CSS, Images/Media, and JavaScript needed for their theme. This folder may also have other names, such as 
resources or 
public.
inc (Custom Functionality): Themes will often have custom PHP classes or files stored in this folder for additional functionality. This folder may also be seen named as 
includes, 
src, and more.
Optional files
This list is nowhere near exhaustive, but it includes some common files used in theme development. (Note: most of the following links lead to external, third-party sites and are not affiliated with WordPress.)
.editorconfig (EditorConfig): Used for configuring formatting, such as line endings and spacing, for code editors.
.gitattributes (Git: Attributes): Configures attributes with the Git version control system.
.gitignore (Git: Ignore): Defines files to ignore when committing code to a Git repository.
CHANGELOG.md (Keep a Changelog): A human-readable log of important changes for each release of your theme.
LICENSE.md (Theme Review: Licensing & Copyright): Defines the license for the theme. Note that all themes submitted to the WordPress theme directory must be licensed under the GPL v2+.
package.json (npm: package.json): Often used to define a build process and development dependencies within a Node environment.
Don’t feel discouraged if you do not understand all of these files and their purposes yet. Again, these are entirely optional elements of a developer’s workflow. Feel free to learn more about them at your own pace at a later time.
Code editor view
Here is a quick editor view of a real-world theme with an advanced structure:
This is vastly more complex than the basics that this documentation is introducing. The point is that, even when building block themes following standard practices, you will have a lot of freedom to customize things. You may want to integrate with version control systems, add in a build process, and more.
So, consider this documentation the foundation in which you can build upon. But there is no harm in keeping it simple and sticking with the basics.

Feedback
Giving Feedback
We welcome suggestions to improve the article, whether it is to add new topics or to rectify mistakes, you’re invited to help.
You can do so in the following ways
Connect to Slack and join #docs and make your suggestion there, one of the Documentation Team members will help
Join the Documentation Team as an editor and edit away!
Open a ticket in the Documentation Issue Tracker repository on GitHub with the “themes” label.
In-page feedback forms are currently planned for the handbooks.

Block Patterns (Archived)
This documentation article has now been archived and replaced with the newer Patterns chapter of the Theme Handbook. Please refer to that page for the most up-to-date information on patterns.
Block patterns are one of the most powerful features at a theme author’s disposal. Introduced in WordPress 5.4, patterns made it easier for users to insert more complex layouts from the block editor while opening a world of possibilities to designers.
What are block patterns?
Essentially, a block pattern is nothing more than one or more blocks that have been pre-configured and presented to the end-user. Think of them as reusable groups of blocks.
They are ideal as starting points for users to insert into their post and page content, but they are also useful when used inside of templates.
Users can insert them directly into a template from the Site Editor or into their content from the Post Editor:
In comparison to template parts, which is a similar feature for reusable groups of blocks, patterns also give you access to PHP. This means that you can internationalize text within them, dynamically add URLs to include images, and more.
Note that users can also create and manage custom patterns from the Appearance > Editor > Patterns screen in the admin. You can also use this screen to manage your own patterns in your development install:
Working with block patterns
In this section, you will learn how to create custom block patterns, register them in your theme, and unregister them. You will also learn some useful tips, tricks, and other methods for working with patterns.
Creating block patterns
The easiest way to learn to create block patterns is to start by putting a few blocks together in the Post Editor. This can be anything you like, but for the purposes of this article, the code shared below will be of a core Cover block with some blocks nested within it, following this structure:
Group
Heading
Paragraph
Buttons
Button
Try recreating this yourself, especially if you are just getting used to working with the block editor. You can also customize this however you like, but it’s recommended to keep this relatively simple for your first time creating a pattern.
Once you’re finished, click the ⋮ (Options) icon in the toolbar and click Copy:
This will give you the code you need to work with, which should be similar to this:
<!-- wp:cover {"overlayColor":"contrast","align":"full"} -->
<div class="wp-block-cover alignfull"><span aria-hidden="true" class="wp-block-cover__background has-contrast-background-color has-background-dim-100 has-background-dim"></span><div class="wp-block-cover__inner-container"><!-- wp:group {"style":{"spacing":{"blockGap":"2.5rem"}},"layout":{"type":"constrained","wideSize":"%","contentSize":"75%"}} -->
<div class="wp-block-group"><!-- wp:heading {"textAlign":"center"} -->
<h2 class="wp-block-heading has-text-align-center">Welcome to My Site</h2>
<!-- /wp:heading -->
<!-- wp:paragraph {"align":"center"} -->
<p class="has-text-align-center">This is my little home away from home. Here, you will get to know me.  I'll share my likes, hobbies, and more.  Every now and then, I'll even have something interesting to say in a blog post.</p>
<!-- /wp:paragraph -->
<!-- wp:buttons {"layout":{"type":"flex","justifyContent":"center"}} -->
<div class="wp-block-buttons"><!-- wp:button {"className":"is-style-outline"} -->
<div class="wp-block-button is-style-outline"><a class="wp-block-button__link wp-element-button">See My Popular Posts →</a></div>
<!-- /wp:button --></div>
<!-- /wp:buttons --></div>
<!-- /wp:group --></div></div>
<!-- /wp:cover -->
For the remainder of this article, you will work with this same pattern, learning how to register it, unregister it, and customize it further.
It’s good practice to wrap most patterns in a Group, Cover, or other container block (i.e., a block that allows nested blocks). This makes it easier for your theme users to move the entire pattern around in the editor. You can also add a CSS class to this outer block for any custom styling that applies to the entire pattern.
Registering block patterns
There are two methods for registering block patterns in WordPress:
By placing files with block markup in them into the 
/patterns folder in your theme.
By manually calling the 
register_block_pattern() function.
The most straightforward route is the first. You’ll learn how to do both in the next sections, but this handbook will recommend using the 
/patterns folder except for in some edge cases.
Using the /patterns directory to register patterns
WordPress will recognize any pattern file placed in your theme’s 
/patterns folder, and it will automatically register it for you, provided that it has a valid pattern file header.
A file header is PHP-commented code with a list of key + value pairs at the top of a file. WordPress parses this information to gather metadata. In this case, the metadata is used to register a block pattern.
For pattern file headers, these are the keys that you can set:
Title: A human-readable title that can be translated.
Slug: A namespaced slug that is unique to your pattern in the form of 
namespace/pattern-name.
Categories: A comma-separated list of categories in which the pattern belongs.
Description: The long description of the registered pattern. Only shown to screen readers.
Viewport Width: The width of the 
<iframe> viewport when previewing the pattern (in pixels).
Inserter: Whether to show the pattern in the inserter. Defaults to 
true.
Keywords: A comma-separated list of keywords related to the pattern for search.
Block Types: A comma-separated list of block types to associate the pattern with.
Post Types: A comma-separated list of post types in which to limit the pattern. Defaults to all post types.
Template Types: A comma-separated list of template types the pattern fits with.
For most patterns, you should at least add the 
Title, 
Slug, and 
Categories fields. Pattern files should look like this:
<?php
/**
 * Title: Hero
 * Slug: themeslug/hero
 * Categories: featured
 */
?>
<!-- Pattern code goes here. -->
Now let’s add the code that you copied from the previous section into the 
/patterns/hero.php file in your theme:
<?php
/**
 * Title: Hero
 * Slug: themeslug/hero
 * Categories: featured
 */
?>
<!-- wp:cover {"overlayColor":"contrast","align":"full"} -->
<div class="wp-block-cover alignfull"><span aria-hidden="true" class="wp-block-cover__background has-contrast-background-color has-background-dim-100 has-background-dim"></span><div class="wp-block-cover__inner-container"><!-- wp:group {"style":{"spacing":{"blockGap":"2.5rem"}},"layout":{"type":"constrained","wideSize":"%","contentSize":"75%"}} -->
<div class="wp-block-group"><!-- wp:heading {"textAlign":"center"} -->
<h2 class="wp-block-heading has-text-align-center">Welcome to My Site</h2>
<!-- /wp:heading -->
<!-- wp:paragraph {"align":"center"} -->
<p class="has-text-align-center">This is my little home away from home. Here, you will get to know me. I'll share my likes, hobbies, and more. Every now and then, I'll even have something interesting to say in a blog post.</p>
<!-- /wp:paragraph -->
<!-- wp:buttons {"layout":{"type":"flex","justifyContent":"center"}} -->
<div class="wp-block-buttons"><!-- wp:button {"className":"is-style-outline"} -->
<div class="wp-block-button is-style-outline"><a class="wp-block-button__link wp-element-button">See My Popular Posts →</a></div>
<!-- /wp:button --></div>
<!-- /wp:buttons --></div>
<!-- /wp:group --></div></div>
<!-- /wp:cover -->
Now if you add or edit a new post in WordPress, you should see your pattern listed in the inserter. Click the Patterns tab and select Featured:
You should also be able to see your pattern listed under Appearance > Editor > Patterns in the WordPress admin.
Using PHP to register patterns
Instead of using the 
/patterns folder to auto-register your patterns, you may choose to manually register them via PHP. You can mix and match both registration methods, but an individual pattern must be registered with only one method.
To register block patterns with PHP, you must use the 
register_block_pattern() function. Here is what its signature looks like:
register_block_pattern( 
	string $pattern_name, 
	array $pattern_properties 
): bool
The function accepts two parameters and returns 
true or 
false, depending on whether the pattern was successfully registered:
$pattern_name: A namespaced slug that is unique to your pattern in the form of 
namespace/pattern-name.
$pattern_properties:
content: The block markup for the pattern.
title: A human-readable title that can be translated.
slug: A namespaced slug that is unique to your pattern in the form of 
namespace/pattern-name.
categories: An array of categories in which the pattern belongs.
description: The long description of the registered pattern. Only shown to screen readers.
viewportWidth: The width of the 
<iframe> viewport when previewing the pattern (in pixels).
inserter: Whether to show the pattern in the inserter. Defaults to 
true.
keywords: An array of keywords related to the pattern for search.
blockTypes: An array of block types to associate the pattern with.
postTypes: An array of post types in which to limit the pattern. Defaults to all post types.
source: The source for the registered pattern. This should be set to 
theme since the pattern is coming from a theme.
templateTypes: An array of template types the pattern fits with.
When registering patterns via PHP, you should do so on the 
init hook. Now try registering your custom pattern by adding this code in 
functions.php (be sure to add your custom markup to the 
content property):
add_action( 'init', 'themeslug_register_patterns' );
function themeslug_register_patterns() {
	register_block_pattern( 'themeslug/hero', array(
		'title'      => __( 'Hero', 'themeslug' ),
		'categories' => array( 'featured' ),
		'source'     => 'theme',
		'content'    => '<!-- Block pattern goes here. -->'
	) );
}
Including patterns in templates
When building themes, patterns are not merely reusable sections of blocks that users can add to their content. That is a nice feature, but the true power of patterns is using them directly in your theme’s front-end output.
You can include patterns in your templates or template parts by adding the Pattern block markup and passing along the pattern slug.
Here is what the Pattern block markup would look like when calling your existing “hero” pattern:
<!-- wp:pattern {"slug":"themeslug/hero"} /-->
That should be relatively straightforward. All you need to know is the 
slug value from when you registered the pattern.
Now try adding it to one of your theme’s templates, such as 
/templates/home.html or 
/templates/index.html below the header. Your template with the pattern code should look similar to this:
<!-- wp:template-part {"slug":"header"} /-->
<!-- wp:pattern {"slug":"themeslug/hero"} /-->
<!-- Some other blocks. /-->
<!-- wp:template-part {"slug":"footer"} /-->
Now test the addition of the pattern in the Site Editor by going to Appearance > Editor > Templates and choosing the template you added it to:
Unregistering block patterns
There are times when you need to unregister block patterns so that they do not appear in the inserter for users. For example, you may want to remove some of the core WordPress patterns, those added by a parent theme (if you’re building a child theme), or those added by third-party plugins.
When you need to unregister a single block pattern, you’ll use the 
unregister_block_pattern() function:
unregister_block_pattern( string $pattern_name ): bool
Like when registering patterns, you’ll also want to unregister on the 
init hook. Because patterns are generally (but not always) registered with the default priority 
10 on 
init, you’ll want to use a higher priority so that your code runs later.
Try unregistering your custom pattern from earlier by adding this code to your 
functions.php file:
add_action( 'init', 'themeslug_unregister_patterns', 999 );
function themeslug_unregister_patterns() {
	unregister_block_pattern( 'themeslug/hero' );
}
Removing core patterns
While you can use 
unregister_block_pattern() to unregister individual core WordPress patterns, you can also choose to get rid of all of them by removing support for the 
core-block-patterns feature.
To remove all core WordPress patterns, add this code to your theme’s 
functions.php file:
add_action( 'after_setup_theme', 'themeslug_remove_core_patterns' );
function themeslug_remove_core_patterns() {
	remove_theme_support( 'core-block-patterns' );
}
Disabling remote patterns
WordPress also automatically loads some patterns remotely from the official Pattern Directory on WordPress.org. There are some situations where you might not want to load these patterns, such as when they don’t match your theme design. You may also want to opt out of calling a remote API on a site that you’re building for a client. Whatever the case, you can disable this by filtering the 
should_load_remote_block_patterns hook.
To disable remote patterns, add this code to your 
functions.php file:
add_filter( 'should_load_remote_block_patterns', '__return_false' );
Tips and tricks
Below, you’ll find various tips, tricks, and other useful features that make block patterns a powerful and flexible part of WordPress theme development.
Internationalizing text in patterns
One of the primary use cases for block patterns is internationalizing text (making it ready for translation). For example, if you have text in a template or template part, the only way to internationalize that text is to move it into a pattern, where you have full access to PHP.
Because pattern files are just PHP, you can use any of the internationalization functions within WordPress. In the below example, you’ll use 
esc_html_e() to both escape the text for security and make it ready for translators.
Try taking your “hero” pattern example and wrapping the custom text inside the Heading, Paragraph, and Button blocks with the 
esc_html_e() function. Your pattern file should look like this:
<?php
/**
 * Title: Hero
 * Slug: themeslug/hero
 * Categories: featured
 */
?>
<!-- wp:cover {"overlayColor":"contrast","align":"full"} -->
<div class="wp-block-cover alignfull"><span aria-hidden="true" class="wp-block-cover__background has-contrast-background-color has-background-dim-100 has-background-dim"></span><div class="wp-block-cover__inner-container"><!-- wp:group {"style":{"spacing":{"blockGap":"2.5rem"}},"layout":{"type":"constrained","wideSize":"%","contentSize":"75%"}} -->
<div class="wp-block-group"><!-- wp:heading {"textAlign":"center"} -->
<h2 class="wp-block-heading has-text-align-center"><?php esc_html_e( 'Welcome to My Site', 'themeslug' ) ?></h2>
<!-- /wp:heading -->
<!-- wp:paragraph {"align":"center"} -->
<p class="has-text-align-center"><?php esc_html_e( "This is my little home away from home. Here, you will get to know me. I'll share my likes, hobbies, and more. Every now and then, I'll even have something interesting to say in a blog post.", 'themeslug' ) ?></p>
<!-- /wp:paragraph -->
<!-- wp:buttons {"layout":{"type":"flex","justifyContent":"center"}} -->
<div class="wp-block-buttons"><!-- wp:button {"className":"is-style-outline"} -->
<div class="wp-block-button is-style-outline"><a class="wp-block-button__link wp-element-button"><?php esc_html_e( 'See My Popular Posts →', 'themeslug' ) ?></a></div>
<!-- /wp:button --></div>
<!-- /wp:buttons --></div>
<!-- /wp:group --></div></div>
<!-- /wp:cover -->
Using images and other assets
Adding dynamic URLs for images and other assets is another important feature of patterns. Because you have PHP access, you can use functions like 
get_theme_file_uri() to output an image URL that’s bundled with your theme, for example.
Try adding an image background to your “hero” pattern’s Cover block. If you need an image, try grabbing one from the WordPress Photo Directory (the example below uses this Nepal night scene photo).
Download an image and save it to your theme’s 
/assets/images folder (or a folder of your choice) and name it 
hero-background.jpg.
Then open your pattern in the editor and upload the image as the background for the Cover block, which should look like this:
As you did earlier, copy the blocks that make up the pattern. You’ll notice that you have two instances of the image URL in your pattern code. It will be a hardcoded URL similar to this:
http://localhost/wp/wp-content/uploads/2023/10/hero-background.jpg
You need to change both of those instances so that they point to the image that is located in your theme’s 
/assets/images folder. For this, you need do two things:
Get the correct URL using a function like 
get_theme_file_uri().
Escape the URL so that it’s safe for output with 
esc_url().
Change the hard coded image URLs to this:
<?php echo esc_url( get_theme_file_uri( 'assets/images/hero-background.jpg' ) ) ?>
Your final pattern code should look like this (note that this example includes internationalized text as explained in the previous section):
<?php
/**
 * Title: Hero
 * Slug: themeslug/hero
 * Categories: featured
 */
?>
<!-- wp:cover {"url":"<?php echo esc_url( get_theme_file_uri( 'assets/images/hero-background.jpg' ) ) ?>","id":3838,"dimRatio":50,"overlayColor":"contrast","align":"full"} -->
<div class="wp-block-cover alignfull"><span aria-hidden="true" class="wp-block-cover__background has-contrast-background-color has-background-dim"></span><img class="wp-block-cover__image-background wp-image-3838" alt="" src="<?php echo esc_url( get_theme_file_uri( 'assets/images/hero-background.jpg' ) ) ?>" data-object-fit="cover"/><div class="wp-block-cover__inner-container"><!-- wp:group {"style":{"spacing":{"blockGap":"2.5rem"}},"layout":{"type":"constrained","wideSize":"%","contentSize":"75%"}} -->
<div class="wp-block-group"><!-- wp:heading {"textAlign":"center"} -->
<h2 class="wp-block-heading has-text-align-center"><?php esc_html_e( 'Welcome to My Site', 'themeslug' ) ?></h2>
<!-- /wp:heading -->
<!-- wp:paragraph {"align":"center"} -->
<p class="has-text-align-center"><?php esc_html_e( "This is my little home away from home. Here, you will get to know me. I'll share my likes, hobbies, and more. Every now and then, I'll even have something interesting to say in a blog post.", 'themeslug' ) ?></p>
<!-- /wp:paragraph -->
<!-- wp:buttons {"layout":{"type":"flex","justifyContent":"center"}} -->
<div class="wp-block-buttons"><!-- wp:button {"className":"is-style-outline"} -->
<div class="wp-block-button is-style-outline"><a class="wp-block-button__link wp-element-button"><?php esc_html_e( 'See My Popular Posts →', 'themeslug' ) ?></a></div>
<!-- /wp:button --></div>
<!-- /wp:buttons --></div>
<!-- /wp:group --></div></div>
<!-- /wp:cover -->
Conditionally loading third-party blocks
There are times when you might want to only use a block if it is registered on the user’s install. This is particularly true for third-party blocks that may be contained in a plugin.
It’s important to note that WordPress will prompt a user to install the block if you add its block markup and it’s not installed. It won’t result in a broken website, so it’s OK to avoid using the method described in this section.
But if you would prefer to hide an unregistered block (or use an alternative), you can conditionally check if a block is registered via the 
WP_Block_Type_Registry::is_registered() method.
This example code shows how to check for the 
core/paragraph block. If it’s registered, it will output the block markup:
<?php if ( WP_Block_Type_Registry::get_instance()->is_registered( 'core/paragraph' ) ) : ?>
	<!-- Add your block markup here. -->
<?php endif ?>
Try applying this method to your registered “hero” block from earlier by wrapping the Paragraph block in this conditional check. Here’s what your pattern code should look like:
<?php
/**
 * Title: Hero
 * Slug: themeslug/hero
 * Categories: featured
 */
?>
<!-- wp:cover {"url":"<?php echo esc_url( get_theme_file_uri( 'assets/images/hero-background.jpg' ) ) ?>","id":3838,"dimRatio":50,"overlayColor":"contrast","align":"full"} -->
<div class="wp-block-cover alignfull"><span aria-hidden="true" class="wp-block-cover__background has-contrast-background-color has-background-dim"></span><img class="wp-block-cover__image-background wp-image-3838" alt="" src="<?php echo esc_url( get_theme_file_uri( 'assets/images/hero-background.jpg' ) ) ?>" data-object-fit="cover"/><div class="wp-block-cover__inner-container"><!-- wp:group {"style":{"spacing":{"blockGap":"2.5rem"}},"layout":{"type":"constrained","wideSize":"%","contentSize":"75%"}} -->
<div class="wp-block-group"><!-- wp:heading {"textAlign":"center"} -->
<h2 class="wp-block-heading has-text-align-center"><?php esc_html_e( 'Welcome to My Site', 'themeslug' ) ?></h2>
<!-- /wp:heading -->
<?php if ( WP_Block_Type_Registry::get_instance()->is_registered( 'core/paragraph' ) ) : ?>
	<!-- wp:paragraph {"align":"center"} -->
	<p class="has-text-align-center"><?php esc_html_e( "This is my little home away from home. Here, you will get to know me. I'll share my likes, hobbies, and more. Every now and then, I'll even have something interesting to say in a blog post.", 'themeslug' ) ?></p>
	<!-- /wp:paragraph -->
<?php endif ?>
<!-- wp:buttons {"layout":{"type":"flex","justifyContent":"center"}} -->
<div class="wp-block-buttons"><!-- wp:button {"className":"is-style-outline"} -->
<div class="wp-block-button is-style-outline"><a class="wp-block-button__link wp-element-button"><?php esc_html_e( 'See My Popular Posts →', 'themeslug' ) ?></a></div>
<!-- /wp:button --></div>
<!-- /wp:buttons --></div>
<!-- /wp:group --></div></div>
<!-- /wp:cover -->
Of course, since the Paragraph block is registered by core WordPress and assuming it hasn’t been unregistered, your Paragraph block should appear in the editor and on the front end. The primary use case for this is to conditionally check third-party blocks.
Conditionally registering patterns
If you need to conditionally register an entire pattern instead of simply conditionally outputting specific parts of it (shown in the previous section), there are two methods to choose from, depending on how you prefer to register patterns.
Conditionally registering patterns in the /patterns folder
If you have used the auto-registration method of placing your pattern in your theme’s 
/patterns folder, there is no true way to conditionally register it. What you must do in this case is unregister the pattern.
Suppose that you wanted to only make the hero pattern you registered earlier available if the 
core/paragraph block is registered. In a real-world scenario, you’d likely be checking for a third-party block, and the 
core/paragraph block is used only for the sake of this example.
Try this code inside of your 
functions.php file to unregister your previously-registered pattern:
add_action( 'init', 'themeslug_unregister_patterns', 999 );
function themeslug_unregister_patterns() {
	if ( WP_Block_Type_Registry::get_instance()->is_registered( 'core/paragraph' ) ) {
		unregister_block_pattern( 'themeslug/hero' );
	}
}
Conditionally registering patterns via register_block_pattern()
If you manually registered your patterns via PHP, you only need to wrap your call to 
register_block_pattern() with your conditional check.
Using the same example as above, try only registering your pattern if the 
core/paragraph block is registered by adding this to 
functions.php:
add_action( 'init', 'themeslug_register_patterns', 999 );
function themeslug_register_patterns() {
	if ( WP_Block_Type_Registry::get_instance()->is_registered( 'core/paragraph' ) ) {
		register_block_pattern( 'themeslug/hero', array(
			'title'      => __( 'Hero', 'themeslug' ),
			'categories' => array( 'featured' ),
			'source'     => 'theme',
			'content'    => '<!-- Block pattern goes here. -->'
		) );
	}
}
Pattern categories
WordPress has several block pattern categories that it registers by default:
featured
about
audio (added in WordPress 6.4)
banner
buttons
call-to-action
columns
contact
footer
gallery
header
media
portfolio
posts
query (use 
posts instead)
services
team
testimonials
text
video (added in WordPress 6.4)
It’s generally best to use these default categories for your theme. This keeps a consistent UI that users will be accustomed to. But there are times when you may want to add your own categories or even remove those that are already registered.
In this section of the article, you’ll learn how to both register and unregister custom block pattern categories.
Registering a pattern category
To register a custom category for putting one or more of your patterns into, you must use the 
register_block_pattern_category() function:
register_block_pattern_category( 
	string $category_name, 
	array $category_properties 
): bool
The function accepts two parameters:
$category_name: A unique ID/slug for the category. It’s good practice to prefix this with your theme slug.
$category_properties: An array of properties for defining further data about the category:
label: A human-readable label/title for the category that may be translated.
description: A description for the category that may be translated.
Try adding a new custom pattern category for your theme. Add this code to your theme’s 
functions.php file:
add_action( 'init', 'themeslug_register_pattern_categories' );
function themeslug_register_pattern_categories() {
	register_block_pattern_category( 'themeslug/custom', array( 
		'label'       => __( 'Theme Name: Custom', 'themeslug' ),
		'description' => __( 'Custom patterns for Theme Name.', 'themeslug' )
	) );
}
Now try adding the 
themeslug/custom category to any block pattern:
<?php
/**
 * Title: Hero
 * Slug: themeslug/hero
 * Categories: featured, themeslug/custom
 */
?>
<!-- Your block markup goes here. -->
Any registered patterns for this category will now appear in the inserter and under Appearance > Editor > Patterns:
Unregistering a pattern category
To unregister a registered pattern category, you must use the 
unregister_block_pattern_category() function:
unregister_block_pattern_category( string $category_name ): bool
The function accepts a single parameter:
$category_name: The name (i.e., slug) of the registered category to unregister.
Try adding this code to your 
functions.php to remove the 
themeslug/custom category you registered in the previous step:
add_action( 'init', 'themeslug_unregister_pattern_categories' );  
  
function themeslug_unregister_pattern_categories() {  
	unregister_block_pattern_category( 'themeslug/custom' );  
}

Block Style Variations
Block style variations (block styles, for short) let you create alternate styles for individual blocks. Registered styles appear in the user interface, allowing users to quickly switch between the default style and any alternates.
Many features, unfortunately, use the term “variations” in their name. This can be confusing at times. The biggest thing to note is that block style variations are not the same thing as global style variations and block variations.
Often, you will see block style variations referred to as “block styles,” as they are in this article, but this should also not be confused with block stylesheets. The two features can be used to work together, but they are not the same thing.
What are block styles?
Under the hood, block styles are nothing more than CSS classes added to a block’s wrapping element with the name of 
.is-style-{name}. This allows you to add custom CSS to alter the block’s design in some way.
In this screenshot, you can see multiple block styles registered for the Image block under the Styles panel, and the core Rounded option is selected:
All that is happening here is that core WordPress and the theme have both registered block styles for the Image block, and the user has selected one of those styles. Then the CSS for that registered style is applied to a block.
Ultimately, block styles are just a standard way to add a class to a block and customize it with CSS.
Users can only apply one style to a block at a time. They cannot combine them using the standard design tools. If you need to allow more options, you might consider building custom design tools. Read the Beyond Block Styles tutorial series on the WordPress Developer Blog to learn how.
PHP-based block styles
Most theme authors will want to register block styles with PHP. Skip ahead to the “JavaScript-based block styles” section if you need or want to work with them via JavaScript.
Registering blocks styles with PHP
To register a block style, use the 
register_block_style() PHP  function. The function’s signature looks like this:
register_block_style( 
	string $block_name, 
	array $style_properties
): bool
The function accepts two parameters and returns 
true or 
false, depending on whether the registration was successful:
$block_name: The name of the block, including both the namespace and slug (e.g., 
core/image).
$style_properties: An array of arguments that can be used to configure the style:
name: (Required) A unique identifier/slug, which is used to generate the class (e.g., 
is-style-{name}).
label: (Required) An human-readable label, which may be translated.
inline_style: Inline CSS to be printed when the style is in use.
style_handle: A handle for a registered stylesheet to load for the style.
is_default: Whether the style should be selected as the default for the block (defaults to 
false).
style_handle currently has a bug where it only enqueues the stylesheet in the editor but not on the front end. Until that linked ticket is addressed, its use is not recommended.
Let’s try creating a block style that gives the Image block a “hand drawn” look so that it looks like this when selected in the editor:
To register this block style, you need to configure it via the 
register_block_style() function and add it as a callback on the 
init hook.
Add the following code to your theme’s 
functions.php file to test it out:
add_action( 'init', 'themeslug_register_block_styles' );
function themeslug_register_block_styles() {
	register_block_style( 'core/image', array(
		'name'         => 'hand-drawn',
		'label'        => __( 'Hand Drawn', 'themeslug' ),
		'inline_style' => '.wp-block-image.is-style-hand-drawn img {
			border: 2px solid currentColor;
			overflow: hidden;
			box-shadow: 0 4px  10px 0 rgba( 0, 0, 0, 0.3 );
			border-radius: 255px 15px 225px 15px/15px 225px 15px 255px !important;
		}'
    ) );
}
If your 
inline_style argument is more than a few lines of CSS code, you may want to add your CSS to a custom block stylesheet instead.
Unregistering block styles with PHP
To unregister a block style that has been registered with PHP, use the 
unregister_block_style() function. Here is a look at its signature:
unregister_block_style(
	string $block_name, 
	string $block_style_name 
): bool
The function accepts two parameters and returns 
true or 
false, depending on whether the registration was successful:
$block_name: The name of the block, including both its namespace and slug (e.g., 
core/image).
$block_style_name: The name/slug of a block style that was registered via PHP.
To unregister the 
hand-drawn block style you registered earlier, you need to add an action function to the 
init hook (note the action call has a later priority of 
99 so that it runs after the earlier registration function, which defaults to 
10):
add_action( 'init', 'themeslug_register_block_styles', 999 );
function themeslug_register_block_styles() {
	unregister_block_style( 'core/image', 'hand-drawn' );
}
You can only unregister block styles with PHP if they have been registered via PHP. If the block style was registered with JavaScript, you must also use JavaScript to unregister it. For more information, see the “Unregistering block styles with JavaScript” section below.
JavaScript-based block styles
To register or unregister block styles via JavaScript, you need to load a JavaScript file on the 
enqueue_block_editor_assets hook.
First, create an 
/assets/js/block-editor.js file in your theme (you can change this name or add it anywhere, but the example below assumes this name and location).
Then add this code to your theme’s 
functions.php file to enqueue your script:
add_action( 'enqueue_block_editor_assets', 'themeslug_block_editor_assets' );
function themeslug_block_editor_assets() {
	wp_enqueue_script(
		'themeslug-block-editor',
		get_theme_file_uri( 'assets/js/block-editor.js' ),
		array( 
			'wp-blocks', 
			'wp-dom-ready', 
			'wp-edit-post' 
		)
	);
}
Registering block styles with JavaScript
To register a block style via JavaScript, you’ll use the 
registerBlockStyle() function, which works similarly to the 
register_block_style() PHP function. It just uses JavaScript syntax.
Let’s use the same example from earlier and register a “hand drawn” Image block style. Add this code to your 
/assets/js/block-editor.js file:
wp.blocks.registerBlockStyle( 'core/image', {
	name: 'hand-drawn',
	label: 'Hand Drawn'
} );
You can also set the 
isDefault argument to 
true if this is meant to be the default block style (it’s 
false by default).
For adding your custom CSS, you’ll need to load a custom block stylesheet or add your CSS by some other means.
Unregistering block styles with JavaScript
There is also an 
unregisterBlockStyle() JavaScript function that is equivalent to the 
unregister_block_style() PHP function. You can use this to unregister any block styles that have been registered via JavaScript.
To avoid a race condition where there’s a conflict between when a block style is registered versus when it is unregistered, you need to ensure that you unregister a block style after it has already been registered. The best way to do this is to add it inside a function callback on 
wp.domReady, which ensures that you unregister after the DOM has loaded.
To unregister the 
hand-drawn block style that you registered via JavaScript, add this to your 
/assets/js/block-editor.js file:
wp.domReady( function () {
	wp.blocks.unregisterBlockStyle( 'core/image', 'hand-drawn' );
} );
You can only unregister block styles with JavaScript if they have been registered via JavaScript. If the block style was registered with PHP, you must also use PHP to unregister it. For more information, see the “Unregistering block styles with PHP” section above.
Customizing block styles via theme.json
It’s possible to customize the design of the core WordPress block styles. This means that you might not need to add custom CSS at all to get the look you’re after.
It is also recommended to use this method if possible for your customizations because they appear in the Appearance > Editor > Styles interface. Plus, your theme users can make their own changes to them if desired.
Let’s try to modify the Outline style of core Button block so that it has a drop-shadow that creates a double-border effect:
To do this, open your 
theme.json file. You’ll need to target the 
styles.blocks.core/button.variations.outline property. It works just like any other style that you can add via 
theme.json.
Try this code snippet in your 
theme.json file:
{
	"version": 2,
	"styles": {
		"blocks": {
			"core/button": {
				"variations": {
					"outline": {
						"border": {
							"color": "var:preset|color|black",
							"radius": "0",
							"style": "solid",
							"width": "3px"
						},
						"shadow": "var:preset|shadow|outlined",
						"spacing": {
							"padding": {
								"top": "0.5rem",
								"bottom": "0.5rem",
								"left": "1.5rem",
								"right": "1.5rem"
							}
						}
					}
				}
			}
		}
	}
}
Feel free to adjust that and customize it to your liking. Then have fun modifying other block styles.
It is not currently possible to customize your custom-registered block styles via 
theme.json. You can only style those registered by core WordPress at the moment. For more information, check out the related feature request on GitHub.
The following are the core WordPress blocks and their styles that you can customize via 
theme.json:
core/button: 
outline, 
fill
core/image: 
rounded
core/quote: 
plain
core/site-logo: 
rounded
core/separator: 
wide, 
dots
core/social-links: 
logos-only, 
pill-shape
core/table: 
stripes
core/tag-cloud: 
outline
For a deeper dive into styling core blocks, read Customizing core block style variations via theme.json on the WordPress Developer Blog.

Block Stylesheets
When styling blocks, you should always do so via the 
theme.json styles property if possible. This ensures that your styles have the best compatibility across the system, working alongside the default WordPress styles, those added by plugins, and user customizations.
But there are times when you simply need to step outside of what’s easily achievable via 
theme.json. For those cases, you should use WordPress’ built-in block stylesheets system.
In this article, you will learn how to register per-block stylesheets, but remember that 
theme.json should be your first choice for styling in most cases.
Why use block stylesheets?
The primary use case for block stylesheets is when you have too much CSS to add to 
styles.blocks.{blockname}.css in 
theme.json. This property allows you to add custom CSS, but it’s only ideal when it’s just a small bit of code. This is because you lose out on syntax highlighting and must place everything in a single line (JSON doesn’t support line breaks).
You may also be tempted to put all your custom CSS into your theme’s primary 
style.css file. That may be OK for some use cases, but the block stylesheets system often offers better performance by only loading the block’s CSS if the block is in use on a page. On the front end, it will also inline this code within the 
<head> area.
Creating separate stylesheets for individual blocks is also beneficial for larger and more complex projects that have a lot of custom CSS for many different blocks. The separation of the files makes it easier to organize and manage your code.
Creating block stylesheets
To create custom block stylesheets, there are three steps you must take:
Decide on an organizational and naming scheme.
Write your custom CSS.
Register your custom block stylesheet(s).
Organizing and naming block stylesheets
Before registering a block stylesheet, you first need to know what folder you will store your custom block stylesheets in. This can be anywhere you choose (there is no standard location), and the code below will assume you are putting block stylesheets in an 
/assets/blocks folder in your theme.
You should also decide on how you will name your CSS files. Again, there is no standard naming convention, but a good option is to use the block namespace and slug like so: 
{namespace}-{slug}.css. With this naming convention, a stylesheet for the 
core/group block would become 
core-group.css.
Here is an example structure of what this could look like with CSS files for a few core blocks:
assets/
blocks/
core-group.css
core-image.css
core-media-text.css
Adding CSS to a block stylesheet
To style a core block, the most important thing you need to know is its CSS class. This is automatically generated according to the block’s namespace and slug in the form of 
.wp-block-{namespace}-{slug}.
Here is an example of styling a block with the namespace and slug of 
super/duper would look like:
.wp-block-super-duper {
	/* custom CSS goes here. */
}
Core WordPress blocks are an exception to this naming rule. Their namespace is 
core, but this is not included in any of the core blocks’ CSS classes. Instead, they use the 
.wp-block-{slug} format.
It’s possible for third-party block developers to change the CSS class that gets output, so this general guide may not always be true for third-party blocks. In those cases, you will want to locate the block’s CSS class in the source code.
Suppose that you wanted to add some custom styling for the core Image block, which has the namespace and slug of 
core/image. You would need to target the 
.wp-block-image class.
Let’s try creating a gradient background, which essentially acts as a faux border for the 
<img> element within the Image block. The goal is to create a style that looks like this:
First, create an 
/assets/blocks/core-image.css file in your theme. Then, add this CSS code to it:
.wp-block-image img {
	padding: 1rem;
	background: linear-gradient(-60deg,#ff5858,#f09819);
}
Because this stylesheet isn’t registered, your custom styles won’t show in the editor or on the front end yet.
Registering a block stylesheet
To register your block stylesheet, you will use the 
wp_enqueue_block_style() function. When registering block stylesheets, you should also execute the code on the 
init hook.
The 
wp_enqueue_block_style() function accepts two parameters:
$block_name: The block name, including both the namespace and slug (e.g., 
core/image).
$args: An array of arguments that is passed to 
wp_register_style():
handle: A unique handle for your stylesheet.
src: The source URL for the stylesheet.
path: The directory path for the stylesheet (needed to inline the CSS in 
<head>).
deps: An array of registered stylesheet handles this stylesheet depends on.
ver: A custom stylesheet version number.
media: The media for which the stylesheet has been defined.
To register your custom stylesheet for the Image block, add this code to your 
functions.php file:
add_action( 'init', 'themeslug_enqueue_block_styles' );
function themeslug_enqueue_block_styles() {
	wp_enqueue_block_style( 'core/image', array(
		'handle' => 'themeslug-block-image',
		'src'    => get_theme_file_uri( "assets/blocks/core-image.css" ),
		'path'   => get_theme_file_path( "assets/blocks/core-image.css" )
	) );
}
You can also configure additional arguments for your call to 
wp_enqueue_block_style(), but the above is the minimum needed for WordPress to inline your CSS code in the 
<head> area of the site.
For a deeper dive into block stylesheets, check out Leveraging theme.json and per-block styles for more performant themes on the WordPress Developer Blog.

Block Variations
The Block Variations API is a powerful feature that allows you to extend any registered blocks. Basically, it gives you the ability to create alternate versions of a block’s settings. This can make it easier for your users to insert blocks without the hassle of going through all of the setup they might need for a specific scenario.
The Block Variations API is often pitched as a plugin developer API. In many cases, plugins are the best place for variations to live. But there are also use cases for theme creators.
Several WordPress features use the term “variations” in their name. This can be confusing at times. The biggest thing to note is that block variations are not the same thing as global style variations and block style variations.
What are block variations?
The simplest explanation of block variations is that they are literally variations on an existing block. Let’s take a look at an example to explore this further.
The Social Icon block is a simple block to add a link to some social site, but WordPress bundles many different variations of this base block to cover a wide range of social sites:
Without the Block Variations API, each of those variations would need to be individually-coded blocks. There are many reasons that would be a bad idea. So instead of writing a block for each social icon, developers only need to make a few configuration changes to create an alternate version of the original block.
There are many, many ways that you could potentially change a block to make it different from its default configuration. This can be something as simple as setting up a Spacer block with your theme’s preferred default spacing. Or it can be as complex as a custom Query Loop block with a complex posts query for the front-page template.
While it is more advanced than some theme features, the API does give you the flexibility to make more complex themes than what is available out of the box.
Block variations vs. block styles
An oft-repeated question is: When should I create a block variation vs. a block style?
The answer is almost always the same as the answer to another question: Can these changes be made through 
theme.json styles or CSS? If yes, you should almost always create a custom block style.
But if you need to change a block’s settings so that it is set up differently when a user inserts an instance of it into a post, a custom block variation is probably the best route to take.
Working with block variations
Block variations require that you work with JavaScript instead of PHP. The examples below do not require a build process, so you can use them as-is.
But the more you work with WordPress’ JavaScript packages, the more likely you’ll want to incorporate build tools into your workflow. It’s possible to use the 
@wordpress/scripts package, originally meant block development, with your theme. For a deeper dive into how this works, read Beyond block styles, part 1: using the WordPress scripts package with themes.
In the next sections, you will learn how to work with block variations by building a simple variation on the WordPress Spacer block, as shown in this screenshot:
For a deeper dive into block variations, check out these tutorials on the WordPress Developer Blog:
An introduction to block variations
Building a book review grid with a Query Loop block variation
Setup: Loading JavaScript
The first step for working with block variations is to create an empty file for adding your custom JavaScript to. This can be at any location you choose, but the code example below will attempt to find a 
block-variations.js in your theme’s 
/assets/js folder.
So your theme structure should look similar to this:
/assets
/js
/block-variations.js
…other files and folders
To load that file in the editor, you must call the 
wp_enqueue_script() function within a callback added to the 
enqueue_block_editor_assets action hook.
Add this code to your theme’s 
functions.php file:
add_action( 'enqueue_block_editor_assets', 'themeslug_enqueue_block_variations' );
function themeslug_enqueue_block_variations() {
	wp_enqueue_script(
		'themeslug-block-variations',
		get_theme_file_uri( 'assets/js/block-variations.js' ),
		array( 
			'wp-blocks', 
			'wp-dom-ready',
			'wp-i18n'
		),
		wp_get_theme()->get( 'Version' ),
		true
	);
}
Take note of the dependencies array (third parameter) within 
wp_enqueue_script(). This includes the 
wp-blocks, 
wp-dom-ready, and 
wp-i18n scripts, which are needed for the JavaScript code in the below examples.
Registering block variations
To register block variations, you must use the 
registerBlockVariation() JavaScript function. Here is a look at the function’s signature:
const registerBlockVariation = ( blockName, variation )
The function accepts two parameters:
blockName: The name of the block (including namespace) to register the variation for.
variation: An optional object for configuring the variation, which may include any of the following properties:
name: A unique, machine-readable slug for your variation.
title: A human-readable title for your variation that should be internationalized.
description: A human-readable description of the variation that should be internationalized if added.
category: The slug of a registered block type category
keywords: An array of keywords to help users discover the variation when searching.
icon: An icon to use to visualize the variation. Either a string or object is accepted.
attributes: An object that overrides the block’s attributes.
innerBlocks: An array to handle the initial configuration of nested blocks.
example: An object that provides structured data for the block preview. Can be set to 
undefined to disable the preview.
scope: A list of scopes where the block can be used. Available options are: 
block, 
inserter, and 
transform.
isDefault: Whether to set the variation as the default variation of the block. Defaults to 
false.
isActive: A function or array of block attributes used to determine if the variation is active when the block is selected.
To learn more about block variations, read the Block Variations API documentation in the Block Editor Handbook.
To build your custom variation, the most important thing is to think about the attributes that you want to control that will set this variation apart from the default block. That’s what makes a variation a variation.
For Spacer block variations, this is likely to be the 
height attribute. Suppose you wanted it to have a default of 
180px. For your variation, you’d need to set 
attributes.height and also check if 
180px is the value of the attribute in the 
isActive callback function.
Try this by pasting this code in your 
block-variations.js file:
const { registerBlockVariation } = wp.blocks;
const { __ } = wp.i18n;
registerBlockVariation( 'core/spacer', {
	name:       'themeslug/spacer',
	title:      __( 'Theme Name: Spacer', 'themeslug' ),
	keywords:   [ 'space', 'spacer', 'spacing' ],
	attributes: {
		height: '180px'
	},
	isActive: ( blockAttributes ) =>
		blockAttributes.height && '180px' === blockAttributes.height
} );
Each block will have its own attributes, so you will need to dive into the block’s code to determine all of the available attributes you may want to overwrite for your variations. That is something beyond what can be covered in this doc, but the above code block should give you a solid starting point.
Unregistering block variations
To unregister a block variation, you must use the 
unregisterBlockVariation() JavaScript function. Here is a look at the function’s signature:
const unregisterBlockVariation = ( blockName, variationName )
The function accepts two parameters:
blockName: The name of the block (including namespace) for the variation you want to unregister.
variationName: The name of the variation to unregister.
Suppose that you wanted to remove the Spacer block variation that you just added from the previous section. All you need to do is plug in the block and variation names.
Add this code at the end of your 
block-variations.js file to test it:
wp.domReady( () => {
	wp.blocks.unregisterBlockVariation( 
		'core/spacer', 
		'themeslug/spacer' 
	);
} );
One important thing to note when unregistering variations is that you should wrap them in a 
wp.domReady() call. This is to ensure that the unregistering process happens later in the loading process after variations have already been registered.

Quick-Start Guide
The first step is always the hardest to take. Now that you’ve made it this far into the Getting Started chapter, you’ve already taken several steps. Congratulations on getting through all of the necessary setup.
In a way, actually building your first theme can feel like another first step, but you are ready to trek out into the wilderness and beyond. Don’t worry—this guide will walk with you as you set out on this journey.
Activating your first theme
One of the best ways to understand how to build themes is to look at and study existing themes.
Even in advanced development circles, one of the cornerstones of sound development is to reuse code. This is because developers understand that this is the most efficient way to get things done, and many try to abide by the “don’t reinvent the wheel” mantra.
Regardless of whether you are a developer, this is sound advice. You don’t need to build everything from scratch. There’s a good chance that most of what you want to do has already been created by someone else.
So, your next step is to activate an existing theme.
Choosing a theme to learn from
Packaged in every version of WordPress since version 3.0 (and named after the year they were released in), the default themes are some of the best to study how themes are built. This is because they are designed with broad use in mind and fully adhere to WordPress coding standards.
Because this handbook primarily focuses on modern, block theming, you should choose one of the newest default themes:
Twenty Twenty-Four
Twenty Twenty-Three
Twenty Twenty-Two
It’s typically best to use the latest default theme. This is because it will be built with the most up-to-date features in mind. Plus, it should already be activated if you’ve recently installed WordPress:
You can also choose any theme from the official Theme Directory to learn from, but for the purposes of this guide, it should be a block theme. For more information on installing and activating themes, read the Work with themes documentation.
If your interests lie in classic WordPress, you should jump forward to the Classic Themes chapter for more details on building classic themes.
Customizing your theme
Once you’ve activated a block theme, take some time to simply have fun exploring and tinkering with the available options in the Site Editor. Essentially, this is an editable, visual representation of your theme in the WordPress admin.
And, as promised earlier in the Getting Started chapter, you can build your theme entirely from this interface without touching a single line of code.
You can locate the Site Editor via Appearance > Editor in the WordPress admin menu. Once opened, your screen should look similar to this:
There are a lot of pieces to this, and you can find yourself lost for hours just tinkering around in the Site Editor. It can be fun, and you’ll learn more about how this integrates with your theme as you read through this handbook. For now, let’s get to the basics of “creating” a theme.
This part of the journey can be entirely self-directed, so feel free to do this at your own pace and in your own way. But most people will want to begin by adjusting their design.
You can do this by first selecting the Styles item in the menu panel:
The Twenty Twenty-Four theme (and many other block themes) include pre-designed style variations, which you can see in the sidebar in the above screenshot. You will learn more about these variations in the Global Settings and Styles chapter, but feel free to use one as a starting point for your own customizations.
The next step is to select the Style Book icon (it looks like an eye). Opening this screen will give you full access to modifying the global styles of the site:
At this point, the world is your oyster—in other words, feel free to let your creativity run wild. But most importantly, get a feel for what settings and styles are available in the interface. This familiarity will come in hand as you dive into more advanced sections of the handbook.
For a deeper dive into using the Style Book, read this guide from the WordPress Developer Blog: The Style Book: a one-stop shop for styling block themes.
Exporting your theme
Once you’ve customized the theme to your liking, be sure to hit the Save button. When you’re ready, you will “create” your first theme.
You have two options for doing this. The first is to use the built-in exporter from the Site Editor in WordPress. The second is to use the Create Block Theme plugin, which has more extensive options available. There are instructions for both methods below.
Exporting from the Styles interface
To export your theme from the Site Editor interface, click the ⋮ (Options) button in the header area. You will see a dropdown of available options. Click the Export option, as shown below:
This will give you a ZIP file with your complete theme in it. The filename will match that of the theme you were working from. In the case of the default Twenty Twenty-Four theme, it will be 
twentytwentyfour.zip.
Congratulations! You have now successfully created your first WordPress theme.
You were assured that you could create a theme without touching code. That was the truth. You have built a theme that can be uploaded to any WordPress website just like any other theme.
But there was a fib—a harmless white lie—mixed in with that truth about there being no code involved.
The theme you downloaded is still named “Twenty Twenty-Four,” and it’s best to rename it so that it’s representative of what you’ve created. To do this, unzip the 
twentytwentyfour.zip folder and rename it to 
your-theme-name.
Then, open the 
style.css file within that folder. You should see something like this at the top of the file:
/*
Theme Name: Twenty Twenty-Four
Theme URI: https://wordpress.org/themes/twentytwentyfour/
Author: the WordPress team
Author URI: https://wordpress.org
...
At the very least, you should adjust those first four lines, particularly the 
Theme Name value. And that’s all the code you really have to touch.
As a final step, zip the file again with whatever utility program you have on your computer for creating ZIP files.
Using the Create Block Theme plugin
The Create Block Theme plugin is an official, first-party plugin that WordPress contributors maintain. Often, you will see new ideas for exporting themes tried and tested here before they land in WordPress.
The plugin is more robust than what you will find in core WordPress, meaning that it has many more options for exporting your theme. This guide will only cover the basics of exporting your theme, but feel free to explore the plugin’s features in more detail.
Once you’ve activated Create Block Theme, you should see a new button in the Site Editor that is displayed as a wrench icon. Click this button to open the Create Block Theme menu.
You will see several options for saving changes, exporting a ZIP, editing theme info, and creating a new theme:
You can use the Export ZIP option to export the theme as you did earlier.
But Create Block Theme offers more customization options that you’ll want to use for truly creating a custom theme. Click on the Create Theme option:
From there, you’ll be able to customize all of the information about your theme to make it unique. Once finished, click the Export Theme button for your new theme.
The one thing that Create Block Theme does not yet do is let you upload a custom screenshot. You’ll still need to add a unique 
screenshot.[png|jpg] file in your theme if you intend to distribute to others.

Reading This Handbook
The goal of this handbook is to walk you through the basics of modern WordPress theme development in its early chapters. Then, work through more advanced topics with each chapter that follows.
The quickest way to learn theme development is to simply read this handbook from beginning to end and follow along with its examples.
Requirements
The biggest requirement for building a WordPress theme is a willingness to learn. You are here reading this handbook, so let’s check that one off the list of requirements.
WordPress theming has changed many times over the years. Today, the pathway for creating one is much lower than it was in the past. You can absolutely create a theme with no coding knowledge. But you will find it much easier to familiarize yourself with a few web languages.
You will see HTML, CSS, PHP, JSON, and JavaScript within the handbook, so it helps to be able to easily recognize what language you are looking at. HTML and CSS are foundational pieces of the web, so those should be prioritized over others.
The following are external resources that you can use to learn more, but there are 1,000s of guides and tutorials around the web:
MDN Web Docs: HTML
MDN Web Docs: CSS
PHP official documentation
MDN Web Docs: JSON
MDN Web Docs: JavaScript
You can get pretty far into theme building via the WordPress user interface, at least by modifying and exporting an existing block theme. But you’ll want to pick up a few more skills to build more advanced features, or to truly create a theme from scratch.
Your next steps
For newcomers
It is time to truly embark on your journey into learning theme development. It is an exciting moment, so get ready for an adventure.
Setting things up: if this is your first time building a theme, or if you just want a refresher on the basics of theme development, your next stop should be the Tools and Setup page. This will help you set up your development environment and determine which tools you need to start off on the right foot.
Getting off to a quick start: once you’re set up, check out the Quick-start guide, which is aimed at giving you a taste of what’s to come. It will walk you through setting up a theme to work with.
Understanding the basics: once you have everything set up and running, move onto the Core Concepts chapter. There, you will learn the foundational principles behind creating WordPress themes.
Afterward, just keep working through each chapter of the handbook.
For seasoned theme authors
Even if you’ve been creating themes for years, it never hurts to give the full handbook a reading from time to time. It is regularly updated, so there may be new content that you haven’t seen before.
Feel free to hop around to find the specific topic you need using the handbook’s navigation links. Whatever the case, the Theme Handbook is here to help you discover a solution.
Feeling pretty hardcore? Jump over to the Advanced Topics chapter.
Can’t remember the naming format for a particular template? Find it in the Template Hierarchy docs.
Need to brush up on 
theme.json? No problem. Check out the Global Settings and Styles documentation.
You can also find theming tutorials and walk-throughs under the Themes category on the WordPress Developer blog if you can’t find the topic you’re looking for in the handbook.
For classic themes documentation
While some of the content in most chapters will apply to classic themes, the docs are primarily geared toward modern block theming. However, there is a dedicated Classic Themes chapter if you need to locate documentation on a specific classic feature.
How to read code examples
Throughout the handbook, you will see code examples, and this section is aimed at helping you understand how to read them.
The handbook will use a consistent “namespace” or “prefix” throughout its pages, generally seen as 
theme_slug or 
theme-slug.  This namespace is meant to be replaced in your theme with one that is unique to it.
But how do you know what your namespace is? The most straightforward way is to use your theme’s name. If your theme is titled Fabled Sunset, you would convert it to the appropriate format for the use case. For example, it would become 
fabled_sunset when used in a PHP function name or 
fabled-sunset as a handle/slug/ID.
The practice of “namespacing” code is decades old. Essentially, a namespace is an identifier for a group of objects created so that they do not conflict with objects in other namespaces.
WordPress has a vast ecosystem of plugins and themes. Each needs a way to distinguish itself from the others. Without unique namespaces, it would get a bit chaotic and errors would arise.
For example, if your theme declared a custom function named 
get_post() instead of 
fabled_sunset_get_post(), your site would fail with a fatal error because WordPress already has a function with this name:
Avoiding these types of errors is the primary reason the handbook will include namespaced or prefixed code examples.
Namespacing examples
Using the fictional theme name Fabled Sunset, let’s look at some examples of formatting your namespace. Don’t worry if you don’t understand these yet or if you do not know anything about code. This is only meant to help you read the handbook.
Usage in script and style handles:
<?php
// theme-slug-editor becomes:
wp_enqueue_script( 'fabled-sunset-editor', ... );
// theme-slug-main becomes:
wp_enqueue_style( 'fabled-sunset-main', ... );
Usage in text domains (used for translations):
<?php
// theme-slug becomes:
esc_html_e( 'Hello, world!', 'fabled-sunset' );
Usage in PHP Functions:
<?php
// theme_slug_func() becomes:
function fabled_sunset_func() {
	// ...
}
Usage in PHP classes:
<?php
// Theme_Slug_Class() becomes:
class Fabled_Sunset_Class() {
	// ...
}
As you read through the handbook, you will learn when to use each case. For now, just know that you should always replace the example namespace with one that is unique to your project.
The WordPress Coding Standards encourages the use of PHP’s built-in namespaces. The same guideline would apply: use your theme’s name to create your namespace. In this case, the namespace for the example theme would be 
Fabled_Sunset or 
FabledSunset. The Theme Handbook uses a prefixed style for PHP function and class names, as shown above. This is primarily because it is simpler for showing one-off code examples.

Tools and Setup
In this document, you will learn about the tools that you will need to get off to a solid start when building WordPress themes. You will also find resources on setting up a development environment for testing your projects.
While it is definitely possible to create and build block themes without any of these tools, they are foundational pieces of a good workflow.
Development environment
When building WordPress themes, it is a good idea to do it within an environment that is separate from a live (i.e., production) site. Before creating your first WordPress theme, you should set up a development environment.
Don’t let this process scare you if it’s your first time. In the long run, you will be happy you learned how to set this up.
Why set up a development environment?
Development environments allow you to test code before it goes live on a production site. You don’t want to change something, push it live, and later realize you created a fatal error that took down the whole website.
By using a development environment, you can test things to ensure they work before they are live.
Your development environment can either be local (on your computer) or on a remote server. But configuring a local environment to work on your theme is beneficial for several reasons:
You do not need an internet connection to build your theme.
You can build your theme without relying on a remote server. This speeds up the building process, and you can see changes instantly in your browser.
You can test your theme from many perspectives. This is important if you plan on releasing it to a larger audience and want maximum compatibility.
Setting up a local development environment
For developing WordPress themes, you need to set up a development environment that is suited to WordPress. This list is not exhaustive, but here are several options to choose from:
@wordpress/env (local WordPress environment package)
Docker
WordPress Studio
Local
MAMP
XAMPP
Varying Vagrant Vagrants (VVV)
For more information, read the Setting Up a Development Environment documentation in the Core Handbook.
Installing WordPress
Before you begin building themes in your development environment, you must also install WordPress.
Some of the development environments include methods for automatically installing an instance of WordPress. You can skip this step if this is the case for you.
To install WordPress on your own, follow the How to install WordPress documentation from the Advanced Administration handbook. Then, of course, come back here and learn more about creating WordPress themes!
Code editor
A good code editor is worth its weight in gold.
Someone Wise
On a more serious note, a good code editor gives you proper syntax highlighting, error reporting, integration with version control systems (VCS), and much more. It’s there to make your life easier.
Technically, you could edit code in a plain text editor, but you’d be missing out on all the best features that true code editors and IDEs (Integrated Development Environments) bring to life.
Editing a theme’s 
single.html template in Visual Studio Code
There are many free and open-source editors to choose from. Here are some of the more popular ones:
Visual Studio Code (VS Code)
VIM
Brackets
Notepad++
GNU Emacs
TextMate
There are also many proprietary editors that are free or cost a fee to use. Whatever you decide to use, pick something you feel comfortable with.
Other development tools
A code editor and development environment are the foundational pieces of creating a WordPress theme. However, there are other tools and resources that you will likely find useful for your project.
Test data
WordPress allows you to import XML files containing real or dummy data for testing your themes. This lets you see how your theme performs with different types of content and layouts. Here are two options for importing:
WordPress.org Theme Test Data
WordPress.com Theme Test Data (includes WordPress.com-specific data)
If nothing else, you need some type of demo/test content to see what your theme looks like in action. You could even create test posts and pages of your own!
Plugins
In addition to test data, there are several WordPress plugins that can help make sure your theme is following standard practices and not producing debugging notices. These are optional but can be useful:
Theme Check: Tests your theme for compliance with the latest WordPress standards and practices.
Debug Bar: Adds an admin bar to your WordPress admin and provides a central location for debugging.
Query Monitor: Allows debugging of database queries, API requests, and AJAX used to generate theme pages and functionality.
Log Deprecated Notices: Logs incorrect function usage, deprecated file usage, and deprecated function usage in your theme.
Monster Widget: Consolidates the core WordPress widgets into a single widget, making it easier to test them all at once (classic themes only).
WordPress.org Theme Review Guidelines
It is a good idea to stay up to date with the theme guidelines provided by the WordPress.org Themes Team. These guidelines are required if you plan to submit your theme to the official Theme Directory, but they are also good principles for anyone creating a theme.
You should also follow the WordPress Coding Standards when writing any code for your theme. This will help make sure what you are creating meets some minimum quality standards.

What Is a Theme?
A WordPress theme represents the design of your website. It can control everything from colors, to fonts, to the entire layout. In essence, what you see when viewing the front-end of your site is shaped by the theme.
Templates from the default Twenty Twenty-Two theme.
There are 1,000s of free WordPress themes in the WordPress.org Theme Directory and even more from third-party directories and shops. Many people and businesses also have bespoke (custom-made) themes for their sites.
What can themes do?
Themes take the content stored by WordPress and display it in the browser. When you create a WordPress theme, you decide how that content looks and is displayed. There are many options available to you when building your theme. The biggest limit is your imagination.
As a theme creator, you can:
Create different layouts, such as one, two or more columns.
Control the typography of the site with custom font choices.
Skin the site with any color scheme you want.
Put a sidebar on the left or right side of the page. Or, have no sidebar at all.
Display featured images alongside posts.
Editing a Twenty Twenty-Three theme style variation.
The WordPress theming system is incredibly powerful. As with every web design project, a good theme is more than defining a layout or two and a few custom colors. The best themes improve engagement with a website’s content in addition to being beautiful.
There really are not many limits to the possibilities. Outside of your imagination, theme creation requires some baseline knowledge, which is covered in the Reading this handbook page of this chapter. That’s what this handbook is all about—teaching you what you need to know to build themes of your own.
Theme types
WordPress supports two primary types of themes: block and classic.
There is also a classic subtype that is called a hybrid theme, and you’ll learn about it below, too. But the most important distinction is block vs. classic.
Technically, you can even build your own theming system altogether. That’s outside the scope of this handbook, but it’s at least worth noting that WordPress lets you build pretty much whatever you set your mind to.
Block themes
Block themes are the modern method of building WordPress themes. They generally follow a standard set of conventions and are built entirely out of blocks. This handbook will primarily focus on building themes using this method because it is the future of the WordPress project.
Block themes rely on HTML-based block templates that contain block markup. Both creators and users can edit the templates in the Site Editor. Users can also customize global settings and styles defined by the theme’s 
theme.json file through the Styles interface.
It’s also possible to export a theme directly from the Site Editor without touching any code. Technically, you cannot create a new theme from scratch entirely from the editor, but you can modify the templates and styles of an existing theme—in essence, creating a custom theme of your own.
Editing a theme’s styles in the Site Editor.
Classic themes
Classic themes use a PHP-based templating system, which is still supported in WordPress today. They are still in wide use because they were built on the theming system that was first introduced in 2005 with the launch of WordPress 1.5. There is a long and deep history of classic theming in WordPress, which continues on. For this reason, the handbook maintains documentation for classic themes in the Classic Themes chapter.
Unlike block themes, classic themes have far fewer standards to adhere to, but there are APIs you can use for specific features. The classic theme creation process also requires some minimal PHP, HTML, and CSS code knowledge, at least.
Editing the default Twenty Twenty theme styles in the customizer.
Hybrid themes
Hybrid themes are merely classic themes that have adopted some modern block-related features, such as global settings and styles or block template parts. This is a widely agreed-upon term by the community, but it is not an “official” theme type. At the end of the day, hybrids are still classic themes.
Become familiar with themes
To build a WordPress theme of your own, you should familiarize yourself with how themes work from a user’s viewpoint. Before diving into the creation process, try installing a theme and playing around with it.
WordPress comes with several default themes, titled Twenty [Year], but you should also try other themes from the Theme Directory just to get a feel for the possibilities.
What are themes made of?
Themes can include many different folders and file types. The list below is non-exhaustive, but it includes some of common things you might see:
Templates (
.html in block themes and 
.php in classic themes)
CSS Stylesheets
JavaScript
PHP
Media (images, audio, video, etc.)
JSON
You will learn more about the specific folders and files used to create a theme in the next chapter: Core Concepts.
What is the difference between themes and plugins?
It is common for there to be overlap between features found in themes and plugins. However, best practices are:
Themes control the presentation of content.
Plugins control the behaviors and features of your site.
Any theme that you create should not add site-critical functionality. Doing so means that a user loses access to that functionality when they change their theme.
For example, say you build a theme with a portfolio feature. Users who build their portfolio with your feature will lose it when they change themes. By leaving critical features to plugins, you make it possible to change the design of a website while its features remain intact.
Remember, some users switch themes often. It is best practice to make sure any functionality their sites require, even if the design changes, is in a separate plugin.

Who Is This Handbook For?
The Theme Developer Handbook is a self-contained resource to help you learn the fundamental principles of creating a WordPress theme. It covers a range of topics that span the basics to advanced development.
You should read this handbook if you want to:
Create a theme based on nothing but your imagination
Build a new theme based on an existing one
Extend another theme by creating a child theme
Understand how themes work
Regardless of your reasons for starting down this adventure, this handbook will help you take the next steps toward building a WordPress theme of your own.
Your skill level
While not a strict requirement, you will get the most out of this handbook if you have a baseline understanding and some experience with web technologies, such as HTML, CSS, and PHP. JavaScript knowledge would be a bonus if you plan to add interactivity to the front end.
Present-day WordPress and its block theme system allow you to customize and export a theme directly from the Site Editor interface:
Exporting a variation of the core Twenty Twenty-Three theme.
With each major WordPress update, its visual building tools become even more robust. Still, having some basic HTML, CSS, and PHP knowledge will help you move along faster.
Unlike block themes, classic themes are built entirely from code. This requires that you be comfortable enough to edit one or more of those languages to some degree.
The Reading this handbook page has more information on the prerequisite knowledge you need to build themes.
At the very least, you must be able to set up and configure a website using WordPress. Otherwise, you won’t be able to test or use the theme that you are building. You can learn more about getting things running in the Tools and setup documentation.
What this handbook covers
This handbook provides the basic information you need to build both block and classic WordPress themes. This includes in-depth coverage of the essential features and APIs that you should know, such as the topics in the Core Concepts chapter. It also dives into tools and techniques for building more advanced themes in the Advanced Topics chapter.
WordPress is a vast subject. HTML, CSS, PHP, accessibility, and other web technologies are even larger. It’d be impossible to cover every aspect of building a website in this handbook alone. Therefore, it is highly-focused on the fundamentals of theme building.
The goal of this handbook is to give you a solid foundation for WordPress theme creation by providing step-by-step instructions for building basic themes and providing resources to further your skills.
If this sounds like something you’d be interested in, come along. You’re in for a journey.

Custom Templates
WordPress lets you register custom templates in 
theme.json. More specifically, you can register single post, page, or CPT (custom post type) templates via the 
customTemplates property.
It’s important to make the distinction that these templates are meant for single post/page/CPT templates and not for other types of templates. When registering these templates, your theme users can select them from the edit post screen, and their post’s design will match the template on the front end of the site.
Custom templates give you a lot of flexibility in designing variations on your default post or page templates. For example, you could create a blank post template that only shows the content, design a page template with a sidebar, or even one that has no sidebars at all. Really, it depends on what your goals are for your theme project.
This documentation is to teach you how to register custom templates via 
theme.json. For a more extensive look into how to build custom templates, check out the Templates documentation.
Adding custom templates
You can register custom templates via the 
customTemplates property in 
theme.json. It accepts an array of template objects, each defining an individual template.
Each object passed to the 
customTemplates array supports these properties:
name: The name of your template file without the file extension.
title: A human-readable title for your template, which may be translated.
postTypes: An array of post type slugs that the template is usable on. This is an optional setting and defaults to the 
page post type.
For block themes, WordPress will look for custom templates (all templates, actually) in the theme’s 
/templates folder. Therefore, if you register a template with the name of 
example, you must also have an 
/templates/example.html file in your theme.
You can add as many custom templates as you want to your theme. Just keep in mind the usability aspect of offering too many choices.
Registering a template
Suppose you wanted to create a template named Content Canvas for both pages and posts. This template will only show the site header, post/page content, and site footer. Your users can select it when they need the full content area to behave as a sort of blank canvas.
The first step you’d take is to create a 
/templates/content-canvas.html file in your theme. Don’t worry about adding anything to it yet; just leave it empty for the moment.
Now register this template in 
theme.json, as shown below:
{
	"version": 2,
	"customTemplates": [
		{
			"name": "content-canvas",
			"title": "Content Canvas",
			"postTypes": [
				"page",
				"post"
			]
		}
	]
}
If you edit a post or page in the WordPress admin, you should see the new Content Canvas option under the Template selector in the Post/Page sidebar panel:
Building a template
Now let’s take care of actually building the template, at least for the sake of demonstration. Remember, you can learn more about building templates in the Templates chapter of the handbook.
Add this code to your 
/templates/content-canvas.html file:
<!-- wp:template-part {"slug":"header","tagName":"header"} /-->
<!-- wp:group {"tagName":"main","layout":{"type":"default"}} -->
<main class="wp-block-group">
	<!-- wp:post-content {"layout":{"type":"constrained"}} /-->
</main>
<!-- /wp:group -->
<!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->
This will give you a working template with an open content area.
To see what this looks like in the site editor, head over to Appearance > Editor in the WordPress admin. Then, select Content Canvas under the Templates section:
This is just a demonstration of what is possible. The real power of custom templates is in what you build with them.

Introduction to theme.json
theme.json is a configuration file that lets you define the global settings, styles, and more for your theme. The file works with both block and classic themes.
When building a block theme, 
theme.json may be the most important file in the entire theme. In a way, it is the foundational piece that trickles down to every other component. That’s why this chapter is one of the most extensive in the handbook.
Some of the things you can do with 
theme.json include (but are not limited to):
Enabling block features in the user interface, such as color, typography, and spacing controls.
Configuring a custom color palette, duotone filters, and background gradients.
Defining typographical features like font families, bundling web fonts, and more.
Adding your own CSS custom properties.
Adjusting the overall design by working within the core styles system.
The settings and styles that you configure in 
theme.json are ultimately reflected on both the front end of the site and WordPress’ built-in editors. As shown in this screenshot, you can see that a variation of the default Twenty Twenty-Three theme as it looks in the Appearance > Editor screen in the admin:
Each part of that design is handled directly in 
theme.json, and the user can further customize it through the built-in Styles interface.
theme.json represents what you might call a “common language” that allows WordPress, your theme, plugins, and users to effectively communicate. Because it is built atop a standardized system, each component plays a role in bringing the overall site to life.
theme.json structure
The 
theme.json file can be broken down into several top-level sections as shown in this code snippet:
{
	"$schema": "https://schemas.wp.org/trunk/theme.json",
	"version": 2,
	"settings": {},
	"styles": {},
	"customTemplates": {},
	"templateParts": {},
	"patterns": []
}
Throughout this chapter, you will learn about each of these properties and how you can work with them to turn the design in your imagination into a working theme.
Customizing the 
theme.json file directly in your theme requires that you have some familiarity with JSON code. You don’t need to be an expert (copying and pasting can get you pretty far), but having some foundational knowledge of how to format JSON will definitely help.
You should also have a baseline understanding of CSS. While you do not need to directly write CSS code in 
theme.json, many of the features are mapped to CSS properties and values. Understanding the relationship between 
theme.json settings and styles and their CSS counterparts will help you in the long run.
For more information on JSON and CSS, read:
MDN Web Docs: CSS
MDN Web Docs: JSON
theme.json properties
As you could see in the previous section, the 
theme.json file has several top-level properties. Some of these accept just a single value, but most have nested sub-properties with their own values.
These are the current top-level properties that you can set in 
theme.json:
version: The 
theme.json schema version you are building for.
$schema: Used for defining the supported JSON schema, which will integrate with many code editors to give you on-the-fly hints and error reporting.
settings: Used to define which block controls appear, configure presets, and more.
styles: Used to apply colors, font sizes, custom CSS, and other styles to the website and blocks.
customTemplates: Metadata for custom templates defined in your theme’s 
/templates folder.
templateParts: Metadata for template parts defined in your theme’s 
/parts folder.
patterns: An array of pattern slugs to be registered from the Pattern Directory.
Adding a version
At the very least, you should set the 
version property in your 
theme.json file. This should be an integer that matches the API version used to read and understand your 
theme.json code.
The API is currently at version 
2. You can always find the most up-to-date version via the 
theme.json Living Reference document.
The bare minimum code that your 
theme.json file should have is:
{
	"version": 2
}
All 
theme.json code examples in this handbook include the 
version property because it should always be set.
Technically, you can leave the version out, but WordPress will read your code as if it was on version 
1 of the API. Using an outdated version may mean that your code will not be valid, at least as it is documented here in the handbook.
 You should always strive to keep up to date with the latest API version and make sure it is set in your 
theme.json file.
Adding a JSON schema
An optional property that you can add to your 
theme.json is a URL to the JSON schema. This can be particularly helpful when working with any modern code editor. Adding the 
$schema property will give you on-the-fly hints and error reporting in many code editors and is highly recommended.
To add support for JSON schema, add this to your 
theme.json file:
{
	"$schema": "https://schemas.wp.org/trunk/theme.json",
	"version": 2
}
Again, this is technically an optional property. But there is rarely a good reason to leave it out. It’s just good development practice to include it.
Adding settings, styles, and more
The other properties available to you via 
theme.json require more in-depth documentation than what can be covered in this introduction. They each have their own pages (and some with multiple sub-pages) in this chapter of the handbook.
Now it’s time to really dive into learning more about 
theme.json. You can take these next documentation steps as you prefer, but these are listed in their recommended reading order:
Settings: Documentation for each of the standard and custom settings that you can configure via 
theme.json.
Styles: Learn how to use the standard design system to apply styles through 
theme.json, which also integrate with the user interface.
Custom Templates: How to register custom post, page, and CPT (custom post type) templates for your theme.
Template Parts: How to register custom template parts that can be reused across your theme.
Patterns**:**How to bundle patterns from the official patterns repository with your theme.
Style Variations: Documentation on creating custom 
theme.json style variations, giving your users alternative designs to choose from.

Patterns
The 
patterns property in 
theme.json lets you bundle patterns from the WordPress Pattern Directory with your theme. This is a neat system that lets you provide a wide variety of patterns that you’ve personally selected without having to design and build them yourself. Any pattern in the directory is available to you.
And if you’re feeling adventurous, you can even submit your custom-designed patterns to the directory. This will let you both bundle them with your theme and let other theme creators and users use your patterns, even when your theme is not installed.
In this document, you will learn how to include directory patterns for your theme’s users with just a few lines of code in 
theme.json.
Adding patterns from the directory
patterns is an optional property that lets you bundle as many or as few patterns as you’d like with your theme. The property accepts an array of pattern slugs, and as long as those patterns exist in the Patterns Directory, they will appear in the Patterns inserter in the WordPress editors.
Here is a look at the 
patterns property in the default 
theme.json:
{
	"version": 2,
	"patterns": []
}
Let’s take a look at one of the patterns from the Pattern Directory: Hero banner with overlap images. To find the slug for the pattern, you need to look in the address bar of your browser, which should give you this URL:
https://wordpress.org/patterns/pattern/hero-banner-with-overlap-images/
The slug is the part of the URL that comes after 
https://wordpress.org/patterns/pattern/. In this case, the slug is 
hero-banner-with-overlap-images (note that the final slash is not included).
To include this pattern with your theme, you need to pass only the slug to the 
patterns array in 
theme.json:
{
	"version": 2,
	"patterns": [
		"hero-banner-with-overlap-images"
	]
}
Now that you’ve got the basics down, pick out a couple of other patterns and add them to your 
patterns array in 
theme.json:
{
	"version": 2,
	"patterns": [
		"fullscreen-cover-image-gallery",
		"hero-banner-with-overlap-images",
		"mixed-shape-gallery"
	]
}
Now you should see your chosen patterns in the Patterns inserter in the UI:
The patterns you include will automatically appear under the categories they are assigned to in the Pattern Directory. These are mapped to the existing patterns registered within WordPress. The patterns from the above example code all have the 
gallery pattern category, so they appear under the Patterns > Gallery tab in the inserter.

Settings
The 
settings property in 
theme.json lets you configure a wide range of settings for a WordPress install. It covers everything from color presets, to enabling typography design tools, to layout, and a little bit of everything in between.
This document contains links for learning about each of these settings, which have their own individual documentation pages.
The settings property
settings is a top-level property in 
theme.json and has multiple nested properties that you can define. And some of those nested properties have multiple levels of nesting of their own.
The following is an overarching look at these properties in the context of a 
theme.json file:
{
	"version": 2,
	"settings": {
		"appearanceTools": false,
		"border": {},
		"color": {},
		"custom": {},
		"dimensions": {},
		"layout": {},
		"position": {},
		"shadow": {},
		"spacing": {},
		"typography": {},
		"useRootPaddingAwareAlignments": false,
		"blocks": {}
	}
}
Settings documentation
Use the following links to explore specific settings that you can configure in your 
theme.json file:
appearanceTools: A catchall setting for enabling multiple other settings.
border: Used for controlling the border width, style, color, and radius.
color: Lets you register a color palette, gradients, duotone and configure color-related settings.
custom: An object for adding custom settings, which are output as CSS custom properties.
dimensions: Lets you configure the minimum height setting.
layout: Used for setting layout properties like the content and wide widths.
lightbox: Lets you configure the image lightbox feature.
position: Currently lets you define support for sticky positioning.
shadow: Lets you configure box-shadow support and define custom shadow presets.
spacing: Used for configuring spacing-related settings, such as margin and padding,
typography: Used for configuring typography-related settings, defining custom font sizes, and registering font families.
useRootPaddingAwareAlignments: A boolean setting for how padding on the root element should work.
blocks: An object for configuring per-block settings.
The Theme Handbook also maintains a reference for available settings based on the 
theme.json schema.

Style Variations
Unlike most things here in the Global Settings and Styles documentation, style variations are not things you define within 
theme.json. Instead, they are “variations” to your existing 
theme.json file that you can offer to users.
A more accurate name for this feature might be Global Settings and Styles Variations. Or simply 
theme.json variations.
What are style variations?
Style variations are essentially alternative versions of 
theme.json that you can ship with your theme. They are custom-named JSON files that are stored in your theme’s 
/styles folder. Any setting or style that you can add to 
theme.json can also be added to your style variation JSON file.
This lets your users pick and choose which variation they want to use on their site. In a way, they are “skins” for your theme.
For example, suppose you’ve created a restaurant theme and have kept the colors and typography pretty basic so that it covers a lot of different restaurant site designs. Further suppose that you wanted to offer more variety, variations on that initial design. You could create a style variation that caters more toward seafood restaurants with fun fonts and an ocean-oriented color palette. Or maybe you want to set the mood for coffee shops that might be running your theme.
That’s where style variations can really shine. You can bundle each of these alternative designs for your theme and let your users decide which is the best option for their site.
Here is a look at the style variations that are bundled with the default Twenty Twenty-Three theme:
When a user selects a style variation, the JSON data is migrated to the site’s database and stored as a user customization. This allows the data to overrule the theme’s primary 
theme.json settings and styles.
Adding custom style variations
The style variations feature is relatively straightforward if you already understand how 
theme.json works, but there are a couple of differences.
The first difference between 
theme.json and style variations are their names and placement in your theme’s folder structure. 
theme.json lives in the root of your theme folder and is considered the default variation. But custom variations must have a unique filename and be placed in the 
/styles folder.
Let’s assume you’ve built that restaurant theme mentioned earlier in this document. Now you want to add a couple of variations named Swashbuckler (for that seafood design) and Latte (for the coffee shop design). This is how your theme files would be organized:
/your-theme-folder
	/styles
		/latte.json
		/swashbuckler.json
	/theme.json
Style variations are simply variations of 
theme.json, so you have full access to everything in the 
theme.json specification at your fingertips.
The second difference between 
theme.json and style variations is the variation title. You can configure this by adding the 
title property to your custom JSON files.
Building off the Latte variation example above, you would open your 
/styles/latte.json file and add it, as shown in this code snippet:
{
	"version": 2,
	"title": "Latte",
	"settings": {},
	"styles": {}
}
The 
title field is used to represent your variation in the user interface. It is not a required field (WordPress will fall back to your variation), but it does make for a nicer user experience.
Style variations vs. child themes
If you are familiar with the concept of child themes, which are covered in the Advanced Topics documentation, you may be wondering what the differences between them and style variations are.
The most obvious difference is that a style variation is limited to a single JSON file that overrides the primary 
theme.json, whereas a child theme can override anything from its parent theme. So it’s probably better to look at the one area they are similar: the JSON file itself.
In a child theme, the 
theme.json simply overrides its parent’s 
theme.json file. In a style variation—and this is where the major difference occurs—the variation’s JSON file overrides the 
theme.json file and its data is saved to the database.
Once a user selects a style variation of a theme, everything in the variation’s JSON file is treated as a user customization. Essentially, WordPress stores that initial data in the same way as if the user had simply designed the colors, typography, spacing, etc. from the interface. This is an important distinction to make because it means that when you update a style variation in a future theme release, the user will not receive those changes if they have already saved the style variation.
It is possible for users to switch to a variation and switch back to the one they were using to get the update.
Style variations can be a great feature to add to your theme, but they have a specific use case. Sometimes child themes make more sense.

Styles
The 
styles property in 
theme.json lets you configure settings at the global level, for individual elements, and individual blocks. WordPress supports a standard subset of the CSS specification, but also allows you to add custom CSS directly in your 
theme.json file.
When possible, it is recommended to add your theme styles via the 
styles property, at least for standard WordPress features. This makes it possible for users to customize them via Appearance > Editor > Styles without CSS specificity issues.
This document contains links for learning about the available style properties and how to apply styles to your theme via its 
theme.json file.
The styles property
styles is a top-level property in 
theme.json and has multiple nested properties that you can define. And some of those nested properties have multiple levels of nesting of their own.
The following is an overarching look at these properties in the context of a 
theme.json file:
{
	"version": 2,
	"styles": {
		"elements": {},
		"blocks": {}
	}
}
The following is an example of what the 
styles property could look like in a custom 
theme.json file. This should give you a feel for how it is structured, but you will dive into this more deeply as you read through this section of the handbook:
{
	"version": 2,
	"styles": {
		"color": {
			"text": "#000000",
			"background": "#ffffff"
		},
		"elements": {
			"button": {
				"color": {
					"text": "#ffffff",
					"background": "#000000"
				}
			}
		},
		"blocks": {
			"core/code": {
				"color": {
					"text": "#ffffff",
					"background": "#000000"
				}
			}
		}
	}
}
Styles documentation
Use the following links to explore configuring styles via 
theme.json file:
Applying Styles: How to apply custom styles to your theme using the standard JSON syntax.
Using Presets: How to use the presets that you’ve configured via the 
settings property in your styles.
Styles Reference: A reference guide for the available style properties that you can use in 
theme.json.

Template Parts
Template parts are small sections (i.e., parts) that you can include in top-level templates. Following the DRY (Don’t Repeat Yourself) principle, they are generally used as sections that need to be reused across multiple templates. Instead of writing the code multiple times, you can break it apart into a single file and include it when needed.
Because this chapter is focused on 
theme.json, the goal of this document is to explain how to register template parts within the 
theme.json file. You can dive more deeply into templates and template parts within the Templates chapter.
In 
theme.json, you can register additional metadata for template parts, such as the title and area the part is assigned to.
Registering template parts
Technically, you can use custom template parts without ever registering them via 
theme.json. But registering them has some distinct advantages:
You can give the part a translatable title that is more appealing in the user interface.
You can assign each part to an area, creating a nicer user experience in the Site Editor.
It plays more nicely with plugins, style variations, and child themes that may grab, filter, or otherwise use the registered metadata in some way.
To register template parts, you must pass an array of objects to the 
templateParts property in 
theme.json. Each object in the array accepts three key/value pairs:
area: The area that the template part belongs to. The default options are 
header, 
footer, and 
uncategorized. You can also assign it to any custom area.
name: The filename of your template part without the extension.
title: A human-readable title for your template, which may be translated.
WordPress will look for template parts in the theme’s 
/parts folder. Therefore, if you register a template part with the name of 
example, you must also have a 
/parts/example.html file in your theme.
You will learn more about template part areas in the Templates chapter. Also, check out the Upgrading the site-editing experience with custom template part areas tutorial on the WordPress Developer Blog for an in-depth walkthrough of creating custom areas.
Registering a template part
The two most common template parts that any theme will register are for a site header and footer. This is also why WordPress has the default areas of 
header and 
footer. You are not required to use these parts or areas, but they are pretty much standard sections for nearly all websites.
For this exercise, let’s register them both. First, add a couple of empty files named 
header.html and 
footer.html in your theme’s 
/parts folder if they do not already exist. You’ll add some block code to them in the next step.
Now register those template parts in 
theme.json:
{
	"version": 2,
	"templateParts": [
		{
			"area": "header",
			"name": "header",
			"title": "Header"
		},
		{
			"area": "footer",
			"name": "footer",
			"title": "Footer"
		}
	]
}
It can be confusing when both the 
area and 
name values match. That’s not always the case, but is often how things look when dealing with the header and footer.
Some theme authors prefer to name the 
header and 
footer template parts 
site-header and 
site-footer to better differentiate them. Feel free to do that if it makes more sense to you. Or rename them to anything you want.
You are not limited to these two common template parts. You can add as many parts as you need for your theme project.
Building a template part
All template parts should be placed in your theme’s 
/parts folder (WordPress also recognizes the 
/template-parts folder for backwards compatibility). So you will now be editing the 
/parts/header.html and 
/parts/footer.html files.
You will learn more about building custom template parts in the Templates chapter. For the purposes of this documentation, just consider the following code snippets as examples that you can customize.
In your 
/parts/header.html file, add this code:
<!-- wp:group {"style":{"spacing":{"padding":{"top":"2rem","bottom":"2rem","right":"2rem","left":"2rem"}}},"layout":{"type":"default"}} -->
<div class="wp-block-group" style="padding-top:2rem;padding-right:2rem;padding-bottom:2rem;padding-left:2rem">
	<!-- wp:group {"layout":{"type":"flex","justifyContent":"space-between"}} -->
	<div class="wp-block-group">
		<!-- wp:site-title /-->
		<!-- wp:navigation {"icon":"menu","layout":{"type":"flex","setCascadingProperties":true,"justifyContent":"right"}} /-->
	</div>
	<!-- /wp:group -->
</div>
<!-- /wp:group -->
Then add this code to your 
/parts/footer.html file:
<!-- wp:group {"style":{"spacing":{"padding":{"top":"2rem","right":"2rem","bottom":"2rem","left":"2rem"}}}} -->
<div class="wp-block-group" style="padding-top:2rem;padding-right:2rem;padding-bottom:2rem;padding-left:2rem">
	<!-- wp:group {"align":"wide","style":{"spacing":{"blockGap":"0"}},"layout":{"type":"flex","orientation":"vertical","justifyContent":"center"}} -->
	<div class="wp-block-group alignwide">
		<!-- wp:site-title {"level":0,"isLink":false,"className":"is-style-normalize"} /-->
		<!-- wp:paragraph -->
			<p>Powered by WordPress.</p>
		<!-- /wp:paragraph -->
	</div>
	<!-- /wp:group -->
</div>
<!-- /wp:group -->
Now go to Appearance > Editor in your WordPress admin and look at the Patterns > Template Parts section. You should see both the Header and Footer areas listed with your custom template parts:
Including a template part
Creating template part files and registering them in 
theme.json does not mean that your parts will automatically appear on the site. Because they are only parts, you must also include them inside of a template.
Remember, you’ll learn more about creating templates in the Templates documentation if you are not already familiar with them. For now, you just need to test how the registration process works.
To include a template part in a top-level template, you must use the Template Part block. The basic markup for this block is:
<!-- wp:template-part {"slug":"your-part-slug"} /-->
So open one of the template files from your theme’s 
/templates folder. Your theme should at least have an 
index.html template there, but you can test with any file.
Now add the calls to the 
wp:template-part block as shown here:
<!-- wp:template-part {"slug":"header","tagName":"header"} /-->
<!-- Other block markup goes here. -->
<!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->
Now you should be able to see both the Header and Footer template parts if you open the top-level template you added them to via Appearance > Editor > Templates in your WordPress admin:

Appearance Tools
settings.appearanceTools is a unique property in 
theme.json that behaves as a catchall for multiple other properties. Compared to other settings that you can configure, this one makes it easy to enable several design-related settings in one go.
Opting into appearance tools
settings.appearanceTools enables several features related to the design or the appearance of a site. By default, the value is set to 
false, so if you choose to not use this property, you can simply not add it to your 
theme.json.
However, if you want to enable it, you can set it to 
true:
{
	"version": 2,
	"settings": {
		"appearanceTools": true
	}
}
This is the equivalent of setting these properties individually in 
theme.json:
{
	"version": 2,
	"settings": {
		"border": {
			"color": true,
			"radius": true,
			"style": true,
			"width": true
		},
		"color": {
			"link": true
		},
		"dimensions": {
			"minHeight": true
		},
		"position": {
			"sticky": true
		},
		"spacing": {
			"blockGap": true,
			"margin": true,
			"padding": true
		},
		"typography": {
			"lineHeight": true
		}
	}
}
As you can see, it can be a major time-saver and create much less work for you. With 
settings.appearanceTools enabled, you can skip setting those properties individually.
You can learn more about what each does via its documentation here in the handbook:
Border
Color
Dimensions
Position
Spacing
Typography
Overwriting appearance tools
Just because you’ve enabled 
appearanceTools doesn’t mean that you cannot disable some features. You can do both.
Suppose that you wanted to enable all appearance tools but disable sticky positioning. You would use this code in your 
theme.json to do this:
{
	"version": 2,
	"settings": {
		"appearanceTools": true,
		"position": {
			"sticky": false
		}
	}
}
This gives you the best of both worlds. You can use 
appearanceTools to enable a large selection of settings but disable others on a case-by-case basis.
Should I enable appearance tools?
There is one caveat to setting 
appearanceTools to 
true in your 
theme.json file: it can automatically opt your theme into design tools in the future. Sometimes, WordPress enables new features when this setting is enabled.
Because no one can reliably predict the future, you need to decide whether you want your theme to support unknown design features that you haven’t tested today.
For many publicly-distributed themes, this will not typically be an issue if you want to provide a lot of flexibility for your theme’s users. By enabling 
appearanceTools, you can give users new design features without updating your theme.
For agencies and freelancers, this could create issues for your clients. Often, these projects are meant to limit the user interface to only specific design tools that the client needs. If WordPress adds new appearance tools in a future update, it’s possible the client will see new and unfamiliar features. For this reason, leaving 
appearanceTools disabled will often make sense.

Blocks
Most settings in 
theme.json let you configure properties at the global level. This means that they apply to all blocks that support them. But WordPress also lets you control this at the block level.
That’s what the 
settings.block property is for—you can configure everything from typography, to colors, to spacing, and more for individual blocks.
Before moving forward with this page of the handbook, it is important to familiarize yourself with at least some of the existing 
theme.json settings. This way, you can apply them on a per-block basis.
How block settings work
In the previous pages of the 
theme.json settings documentation, you learned how to configure specific properties at the global level. Essentially, this means that they are applied to all blocks that support the specific property/feature.
You would have configured many of these properties in your 
theme.json (shortened for example—you can review all available properties via the main settings documentation):
{
	"version": 2,
	"settings": {
		"border": {},
		"color": {},
		"custom": {},
		"spacing": {},
		"typography": {}
	}
}
But there are times when you need to add settings at the individual block level, and anything set for the block will overrule its global setting. So let’s explore an example that shows block-specific settings overwriting the global settings.
For this example, you will create a custom color palette, which you can learn about in the color settings documentation. This will be applied globally and used for every block’s color picker. Then, you will create a custom color palette for the Cover block that’s only shown for the Cover block.
First, add your global color palette in 
theme.json with two colors named 
base and 
contrast:
{
	"version": 2,
	"settings": {
		"color": {
			"palette": [
				{
					"color": "#0284c7",
					"name": "Base",
					"slug": "base"
				},
				{
					"color": "#ffffff",
					"name": "Contrast",
					"slug": "contrast"
				}
			]
		}
	}
}
Now add a Cover block and some nested text in the WordPress editor, saving the Text and Overlay colors for the block to your two custom colors:
As you can see, the Cover block currently uses the global color palette that you configured in your 
theme.json file.
Suppose that you wanted the Cover block to use an orange color palette. You can configure that by targeting 
settings.blocks[core/cover].color.palette in your 
theme.json file and passing an array of custom colors.
Add this new section to your existing 
theme.json so that it looks like this:
{
	"version": 2,
	"settings": {
		"color": {
			"palette": [
				{
					"color": "#0284c7",
					"name": "Base",
					"slug": "base"
				},
				{
					"color": "#ffffff",
					"name": "Contrast",
					"slug": "contrast"
				}
			]
		}
		"blocks": {
			"core/cover": {
				"color": {
					"palette": [
						{
							"color": "#ea580c",
							"name": "Base",
							"slug": "base"
						},
						{
							"color": "#fff7ed",
							"name": "Contrast",
							"slug": "contrast"
						}
					]
				}
			}
		}
	}
}
As shown in the 
theme.json example, you use the same organizational structure for block settings as you do for global settings (i.e., 
settings.color at the global level but 
settings.blocks[core/cover].color at the block level).
If you refresh your browser window, your Cover block should now show the new colors:
If you check other blocks, they will still use the global color palette. Only the Cover block will use this custom orange palette.
Per-block color palettes are just the tip of the iceberg. You can configure any 
theme.json for any block (assuming the block supports it). This gives you an incredible amount of control over how your theme works.
When targeting a block’s settings, you must know both its namespace and slug. Above, you learned that the Cover block has the namespace (
core) and slug (
cover), creating the namespace/slug combination of 
core/cover. All core WordPress blocks have the 
core namespace, and you can find this information for any block (including from third-party plugins) in its 
block.json file.
Default block settings
Believe it or not, WordPress actually configures a couple of default block settings in 
theme.json. Generally, this would be left to themes, but these settings are primarily enabled for backward compatibility with features from older versions of WordPress.
WordPress enables a few settings for the Button and Pullquote blocks by default. Here is what this looks like in the default 
theme.json:
{
	"version": 2,
	"settings": {
		"blocks": {
			"core/button": {
				"border": {
					"radius": true
				}
			},
			"core/pullquote": {
				"border": {
					"color": true,
					"radius": true,
					"style": true,
					"width": true
				}
			}
		}
	}
}
You can overwrite these block-specific settings in your 
theme.json file just as you learned to do in the previous section of this documentation.
If you are wondering why some of your global settings do not seem to apply to certain blocks, particularly Button and Pullquote, it is likely because they are being set at the block level. You will need to override these in 
settings.blocks in your 
theme.json if you want a different behavior.

Border
The 
settings.border property in 
theme.json gives you control over the global border settings for blocks in WordPress. It’s important to note that this lets you configure the available settings in the user interface, not the border styles themselves.
Each of the border settings maps to a control at the individual block level and in the Styles interface for blocks, letting you curate which controls are available to your theme users:
Border settings
WordPress supports four border settings that you can configure via the 
settings.border property in 
theme.json. Each of them allows you to enable or disable a specific border feature and accepts a boolean (
true or 
false) value:
color: Enables/Disables the border-color picker.
radius: Enables/Disables the border-radius control.
style: Enables/Disables the border-style selector (users have the option of 
solid, 
dashed, or 
dotted).
width: Enables/Disables the border-width input.
By default, all border properties are set to 
false, as shown in this example 
theme.json code:
{
	"version": 2,
	"settings": {
		"border": {
			"color": false,
			"radius": false,
			"style": false,
			"width": false
		}
	}
}
As of WordPress 6.3, 
color, 
style, and 
width are intertwined. If any one of them is set to 
true, the others will be available as options within the user interface.
Also, setting the 
radius option to 
false does not work for the Button block. The border-radius control in the editor always appears.

Color
Color is one of the primary components of design. You can create a theme that is dark and moody, fun and lighthearted, or clean and corporate. Which colors you choose will define how the world sees your theme, and WordPress provides a range of color-specific configuration options that you can set.
The 
settings.color  property in 
theme.json gives you full control over how colors, gradients, and more work within your theme. Primarily, the goal is for configuring whether specific controls appear in the user interface, but it also lets you register custom presets that users can select.
Color settings
color is an object that’s nested directly within the top-level 
settings property in 
theme.json. It is used to configure multiple color-specific settings that appear in the user interface.
Take a look at the 
color property in the context of a 
theme.json file with its default values:
{
	"version": 2,
	"settings": {
		"color": {
			"background": true,
			"custom": true,
			"customDuotone": true,
			"customGradient": true,
			"defaultDuotone": true,
			"defaultGradients": true,
			"defaultPalette": true,
			"duotone": [],
			"gradients": [],
			"link": true,
			"palette": [],
			"text": true
		}
	}
}
As you can see, most of the settings accept a boolean value, meaning that you can set them to either 
true or 
false. Others, like 
duotone, 
gradients, and 
palette take an array of values. These are the ones where you can register custom presets, and you will learn how to create them in this doc.
Color settings can largely be broken down into four groups that let you:
Enable or disable settings in the UI.
Enable or disable user customizations of colors, duotones filters, and gradients.
Enable or disable the core WordPress color, duotone, and gradient presets.
Register custom color, duotone, and gradient presets.
In the following sections, you will learn how each of these work.
Text, background, and link settings
In the block editor, you will often see Text, Background, and Link settings under the Color panel for a block, at least for those blocks that opt into support of one or more of them.
These options appear like this in the interface:
But just because a block registers support for text, background, and link colors doesn’t mean that your theme must also support them. That’s entirely up to you.
WordPress lets you decide whether your theme supports any or all of the settings by defining the 
background, 
link, and 
text properties under 
settings.color in 
theme.json:
{
	"version": 2,
	"settings": {
		"color": {
			"background": true,
			"link": true,
			"text": true
		}
	}
}
By default, all are set to 
true, so their associated controls will appear in the block interface. If you want to disable a feature, you only need to set its value to 
false in your 
theme.json.
For an exercise, try disabling the background color but still allow text and link colors:
{
	"version": 2,
	"settings": {
		"color": {
			"background": false,
			"link": true,
			"text": true
		}
	}
}
Some core WordPress blocks and third-party blocks may have other color options that users can configure. These cannot be enabled or disabled via 
theme.json since they are not a standard component of the color system.
Enabling and disabling user customizations
One of the major decisions that you will need  to make for your theme is whether you want to allow users to create custom colors. On the one hand, enabling custom colors gives users a ton of flexibility and freedom to truly make their site their own. But maybe you’ve put in a lot of work getting the color scheme just right and want to make sure the user is only picking colors from a predetermined palette.
This may change depending on whether you are building a publicly-distributed theme vs. one for a client. Each project is unique, and you get to be the judge on what’s best for your design.
WordPress currently allows user-customized colors for three different features, which you can enable or disable via 
theme.json:
custom: Whether the user can create and use custom colors.
customDuotone: Whether the user can create custom duotone filters (typically used for overlays on blocks with images).
customGradient: Whether the user can create custom background gradients.
By default, each of these features are enabled in 
theme.json:
{
	"version": 2,
	"settings": {
		"color": {
			"custom": true,
			"customDuotone": true,
			"customGradient": true
		}
	}
}
User-customized colors
When the 
settings.colors.custom value is set to 
true (the default), users will be able to define custom colors for individual blocks, as shown here:
Because this is enabled by default, try turning it off by setting the property to 
false in your 
theme.json file:
{
	"version": 2,
	"settings": {
		"color": {
			"custom": false
		}
	}
}
Now users will only be able to select from preset colors.
User-customized duotone filters
Duotone filters are generally supported by blocks that display an image. The filter is applied as an overlay above the image, creating a duotone effect. The two-color filter allows users to select a shadow and highlight color.
By default, users can create custom duotone filters as shown here:
Since custom duotone filters are enabled by default, you must set the 
settings.color.customDuotone property to 
false if you do not want to allow users to add custom colors:
{
	"version": 2,
	"settings": {
		"color": {
			"customDuotone": false
		}
	}
}
User-customized gradients
Like most other color settings, custom gradients are enabled by default. This allows your theme users to define a gradient background for any block that supports it as shown here:
If you’ve carefully fine-tuned the gradients you want available to the user or simply want to disable custom gradients altogether, you can turn this feature off by setting 
settings.color.customGradient to 
false in 
theme.json:
{
	"version": 2,
	"settings": {
		"color": {
			"customGradient": false
		}
	}
}
Default WordPress presets
WordPress creates its own presets for each of the color features. As is the case with user-defined colors, you will need to decide whether you want to give users access to these. They will often clash with your theme’s color palette, but you may also opt to give users complete freedom to decide on their own.
WordPress currently allows user-customized colors for three different features, which you can enable or disable via 
theme.json:
defaultDuotone: Whether the user can select from WordPress’ default duotone filter presets (typically used for overlays on blocks with images).
defaultGradients: Whether the user can select from WordPress’ default background gradient presets.
defaultPalette: Whether the user can select colors from WordPress’ default color palette.
By default, each of these features are enabled in 
theme.json:
{
	"version": 2,
	"settings": {
		"color": {
			"defaultDuotone": true,
			"defaultGradients": true,
			"defaultPalette": true
		}
	}
}
It’s important to note that, even if these settings are disabled, WordPress will still generate the CSS custom properties for its presets. This is for backward-compatibility and so that users do not lose colors, gradients, or duotone filters that they have previously chosen when using another theme.
Default color palette
WordPress ships with its own color palette, which is enabled by default for themes that have not opted out of it. It contains the following colors:
Black
Cyan bluish gray
White
Pale pink
Vivid red
Luminous vivid orange
Luminous vivid amber
Light green cyan
Vivid green cyan
Pale cyan blue
Vivid cyan blue
Vivid purple
Color presets are available for the Text, Background, Link, and potentially other color controls as shown in this screenshot:
There are times when you might want to disable the core WordPress colors, and you can do so by setting 
settings.color.defaultPalette to 
false in 
theme.json:
{
	"version": 2,
	"settings": {
		"color": {
			"defaultPalette": false
		}
	}
}
Default duotone filters
WordPress has several default duotone filter presets that it defines:
Dark Grayscale
Grayscale
Purple and yellow
Blue and red
Midnight
Magenta and yellow
Purple and green
Blue and orange
These will appear for blocks that support duotone filters (generally used as an overlay for blocks with images), as shown here:
If you do not want to allow your theme users to select from the default duotone presets, you must set 
settings.color.defaultDuotone to 
false in 
theme.json:
{
	"version": 2,
	"settings": {
		"color": {
			"defaultDuotone": false
		}
	}
}
Default gradients
By default, WordPress defines several gradients for users to pick and choose from. These can be added to blocks that support gradient backgrounds:
Vivid cyan blue to vivid purple
Light green cyan to vivid green cyan
Luminous vivid amber to luminous vivid orange
Luminous vivid orange to vivid red
Very light gray to cyan bluish gray
Cool to warm spectrum
Blush light purple
Blush bordeaux
Luminous dusk
Pale ocean
Electric grass
Midnight
They appear as shown here in the Background > Gradient control in the user interface:
The core WordPress gradient presets are enabled by default, but there are times when you may want to disable them for your theme. You can do so by setting 
settings.color.defaultGradients to 
false in your 
theme.json:
{
	"version": 2,
	"settings": {
		"color": {
			"defaultGradients": false
		}
	}
}
Registering custom color presets
Just like WordPress defines its own color, duotone, and gradient presets, so can you. This is a powerful feature that allows you to customize how your theme looks on the front end of the site and which colors your theme users can select from in the block editor.
You can set presets for three different features via 
theme.json:
duotone: An array of duotone filters that a user can choose from (typically used for overlays on blocks with images).
gradients: An array of background gradient objects that a user can choose from.
palette: An array of color objects that a user can choose from.
Here is what this would look like in 
theme.json (note that there are no presets yet registered):
{
	"version": 2,
	"settings": {
		"color": {
			"duotone": [],
			"gradients": [],
			"palette": []
		}
	}
}
WordPress will automatically generate CSS custom properties for each of your presets in the form of 
--wp--preset--{type}--{slug}. So a color palette preset with the slug of 
contrast will become 
--wp--preset--color--contrast.
You can access these in your 
theme.json styles via the CSS custom property itself or through a special naming convention of 
var:preset|{type}|{slug}. You will learn more about this in the 
theme.json Styles documentation.
WordPress will also sometimes generate CSS classes based on the preset. For example, the 
contrast color palette preset will have an associated class for 
.has-contrast-color when used as a block’s text color and 
.has-contrast-background-color when used as a background.
Custom color palette
When building a theme you will almost always want to register your own color palette. For some themes, this may be as simple as a couple of colors. Others could potentially include dozens of colors.
In the end, it’s your theme, and WordPress gives you the tools to build your design.
You can register custom colors via the 
settings.color.palette property in 
theme.json:
{
	"version": 2,
	"settings": {
		"color": {
			"palette": []
		}
	}
}
The 
palette property accepts an array of color objects, and each of those objects has three properties that you must set:
color: A valid CSS color value.
name: The label for your color, which will be internationalized (so that it can be translated) and shown to the user in some contexts, such as tooltips.
slug: A unique machine-readable slug/ID for your color. This is used to generate CSS custom properties and CSS classes.
Suppose you wanted to register three colors named Base, Contrast, and Primary for your theme. They would appear in the color picker like so:
For your custom colors to appear in the interface, you must add them to the 
settings.color.palette array as shown in this code snippet:
{
	"version": 2,
	"settings": {
		"color": {
			"palette": [
				{
					"color": "#ffffff",
					"name": "Base",
					"slug": "base"
				},
				{
					"color": "#000000",
					"name": "Contrast",
					"slug": "contrast"
				},
				{
					"color": "#89CFF0",
					"name": "Primary",
					"slug": "primary"
				}
			]
		}
	}
}
You can add as few or as many colors as you want, and there are no official naming schemes.
Despite there not being an official naming scheme for colors, the 
base and 
contrast slugs are de facto standards that were set forth by the Twenty Twenty-Three default theme. It is recommended to use 
base for the site background and 
contrast for text. This provides the greatest future-proofing and compatibility between themes. It also gives plugin authors a standard set of fallback colors when needed.
Custom gradients
Like colors, you can also register a custom set of gradient presets. And there are no limits on the number of gradients your theme can support, so go wild and have a bit of fun!
You can register custom gradients via the 
settings.color.gradients property in 
theme.json:
{
	"version": 2,
	"settings": {
		"color": {
			"gradients": []
		}
	}
}
The 
gradients property accepts an array of gradient objects, and each of those objects has three properties that you must set:
gradient: A valid CSS background gradient value.
name: The label for your gradient, which will be internationalized (so that it can be translated) and shown to the user in some contexts, such as tooltips.
slug: A unique machine-readable slug/ID for your gradient. This is used to generate CSS custom properties and CSS classes.
Let’s suppose you have a couple of gradients named Emerald and Fabled Sunset that you want to add for your theme as shown here:
Add the following to your 
theme.json to register them:
{
	"version": 2,
	"settings": {
		"color": {
			"gradients": [
				{
					"gradient": "linear-gradient(to right, #10b981, #64a30d)",
					"name": "Emerald",
					"slug": "emerald"
				},
				{
					"gradient": "linear-gradient(-225deg,#231557,#44107a 29%,#ff1361 67%,#fff800)",
					"name": "Fabled Sunset",
					"slug": "fabled-sunset"
				}
			]
		}
	}
}
Custom duotone filters
Like colors and gradients, you can register any number of custom duotone filters for your theme. This will allow your users to apply customizations directly to Image and other blocks that support duotone.
You can register custom gradients via the 
settings.color.duotone property in 
theme.json:
{
	"version": 2,
	"settings": {
		"color": {
			"duotone": []
		}
	}
}
The 
duotone property accepts an array of duotone objects, and each of those objects has three properties that you must set:
colors: An array containing two valid CSS color values.
name: The label for your duotone filter, which will be internationalized (so that it can be translated) and shown to the user in some contexts, such as tooltips.
slug: A unique machine-readable slug/ID for your duotone filter. This is used to generate CSS custom properties and CSS classes.
Suppose you wanted to create to create two duotone filters—one for red shadows and highlights and a similar one for blues, as shown below:
To register the Red and Blue dutone filters, add this code to your 
theme.json:
{
	"$schema": "https://schemas.wp.org/trunk/theme.json",
	"version": 2,
	"settings": {
		"color": {
			"duotone": [
				{
					"colors": [
						"#450a0a",
						"#fef2f2"
					],
					"name": "Red",
					"slug": "red"
				},
				{
					"colors": [
						"#172554",
						"#eff6ff"
					],
					"name": "Blue",
					"slug": "blue"
				}
			]
		}
	}
}
Duotone does not currently support CSS custom properties or references and cannot be dynamically generated. There is an open ticket to solve this issue.

Custom
The 
settings.custom property is unique among other settings in 
theme.json. As its name implies, it is a custom property. This means that you get to decide how to use it. Essentially, it provides a method for creating CSS custom properties that you might need elsewhere in your theme.
In this document, you will learn what the 
custom property is for and how you can use it in your theme.
Overview of the custom setting
The 
settings.custom property accepts a single object, and this object can be used to store other values. The individual object values must be valid CSS values or an object with nested key/value pairs.
Here is an example snippet from 
theme.json with no custom values set:
{
	"version": 2,
	"settings": {
		"custom": {}
	}
}
The great thing about the 
settings.custom object is that you can use it to create your own CSS custom properties. When you add a key and value to the object, WordPress will automatically generate the CSS custom property, assign the value, and load it for you.
The generated CSS custom property will follow this pattern: 
--wp--custom--{key}--{value}.
Suppose you wanted to use the key of 
fruit and give it a value of 
apple. Add this to your 
theme.json file:
{
	"version": 2,
	"settings": {
		"custom": {
			"fruit": "apple"
		}
	}
}
WordPress will then generate this CSS:
body {
	--wp--custom--fruit: apple;
}
How CSS custom properties are generated
As you learned above, the 
settings.custom.fruit key name will generate the 
--wp--custom--fruit variable in CSS. But there are other cases too.
Automatic hyphenation
WordPress will automatically hyphenate camel-cased names. For example, 
lineHeight in the following example will become 
line-height:
{
	"version": 2,
	"settings": {
		"custom": {
			"lineHeight": "1.4em"
		}
	}
}
This will create the following CSS:
body {
	--wp--custom--line-height: 1.4em;
}
Numbers are handled the same as uppercase letters when used as a key. For example, a key of 
abc123 will become 
abc-1-2-3 in the resulting CSS.
Nested properties
Building off the above example, suppose you wanted to create several line-height CSS custom properties for use in your theme. For this, you might want to create an object under 
settings.custom.lineHeight instead of a single value.
Add the following to your 
theme.json file:
{
	"version": 2,
	"settings": {
		"custom": {
			"lineHeight": {
				"xs": "1",
				"sm": "1.25",
				"md": "1.5",
				"lg": "1.75"
			}
		}
	}
}
WordPress will automatically use this nested structure when generating the CSS custom property names.
This will generate this CSS:
body {
	--wp--custom--line-height--xs: 1;
	--wp--custom--line-height--sm: 1.25;
	--wp--custom--line-height--md: 1.5;
	--wp--custom--line-height--lg: 1.75;
}
There is no limit to the amount of nesting you can do, but keep in mind that the more you nest, the longer your CSS custom property names become.
Practical usage
What you use the 
settings.custom property for is entirely up to you. At its core, all it really does is generate CSS custom properties, which don’t do anything on their own. Custom properties must also be used in CSS.
In the previous 
theme.json example above, you created a set of line-heights. There are a number of ways you can put these into practical use.
Use in theme.json styles
In the Styles documentation, you will learn how to apply styles to the root element, elements, and blocks via 
theme.json. This will be one of the primary use cases for integrating with 
settings.custom.
Suppose you wanted to register the same set of line-heights from above and make use of them. Maybe you want to set the root element to the 
md line-height and Paragraph blocks to 
lg. You can access each line-height property via 
var:custom|line-height|md and 
var:custom|line-height|lg, respectively.
Use this code in your 
theme.json file:
{
	"version": 2,
	"settings": {
		"custom": {
			"lineHeight": {
				"xs": "1",
				"sm": "1.25",
				"md": "1.5",
				"lg": "1.75"
			}
		}
	},
	"styles": {
		"typography": {
			"lineHeight": "var:custom|line-height|md"
		}
		"blocks": {
			"core/paragraph": {
				"typography": {
					"lineHeight": "var:custom|line-height|lg"
				}
			}
		}
	}
}
You can also reference the values via their CSS custom properties. For example, instead of using 
var:custom|line-height|md, use 
var( --wp--custom--line-height--md ).
Remember, you will learn more about styling via 
theme.json from the Styles documentation. You can use what you learn there to combine with the techniques outlined here.
Use in CSS
There are times when you might need to reference the generated CSS custom properties directly in CSS, such as your 
style.css file. To do this, you must use the CSS custom property name.
Suppose you needed to target a class with the name of 
.example-class and to give it the 
sm line-height that you’ve registered. Use this code in your CSS:
.example-class {
	line-height: var( --wp--custom--line-height--sm );
}

Dimensions
The 
settings.dimensions property in 
theme.json gives you control over the global dimensions settings for blocks. This property lets you decide which dimension controls are available in the user interface.
In this document, you will learn what the 
dimensions property is for and how you can use it in your theme.
Dimensions settings
dimensions is an object that’s nested directly within the top-level 
settings property in 
theme.json. Currently, it only lets you set a single property:
minHeight: A boolean value for enabling block support for the Minimum Height control.
Take a look at the 
dimensions property in the context of a 
theme.json file with its default values:
{
	"version": 2,
	"settings": {
		"dimensions": {
			"minHeight": false
		}
	}
}
Minimum Height
The 
settings.dimensions.minHeight property lets you control whether the Minimum Height field appears for blocks that have opted into support for the feature. As of WordPress 6.3, the only core WordPress blocks that do are Group and Post Content.
To enable support for the control, you must set the property’s value to 
true in 
theme.json:
{
	"version": 2,
	"settings": {
		"dimensions": {
			"minHeight": true
		}
	}
}
This will enable the control in the interface. As shown in this screenshot, the Minimum Height field appears for the Group block (Stack variation):

Layout
The 
settings.layout property in 
theme.json is an object that stores layout-related settings that you can configure. At the moment, it is used for setting “content” and “wide” widths, but it could also be used for other settings in the future.
In this document, you will learn what the 
layout property is used for and how you can use it in your theme.
Layout settings
layout is an object that’s nested directly within the top-level 
settings property in 
theme.json. Within that object, you can define two settings:
contentSize: A valid CSS length value for defining the default width for content. It is typically used for controlling the width of the post content and related areas on the page.
wideSize: A valid CSS length value for defining the default wide alignment width, which is generally between the content size and full viewport width.
Take a look at the 
layout property in the context of a 
theme.json file with its default values:
{
	"version": 2,
	"settings": {
		"layout": {
			"contentSize": "",
			"wideSize": ""
		}
	}
}
Content size
The 
settings.layout.contentSize property is primarily useful for defining the width of a site’s content area. Think of this as the default width of your site. You can break outside of this by applying the “wide” (below) or “full” width to a block. The content width is merely the foundation.
In almost any design, you will want to limit this width to something that is comfortable to read, especially if the content is going to include text. This is a value that you will need to determine for yourself, but a good rule of thumb is that you should have 45-75 characters of text per line (though some guidelines differ slightly on the number range). Of course, your default font-family and font-size are crucial pieces to figuring this out.
Try configuring a content size in your 
theme.json file:
{
	"version": 2,
	"settings": {
		"layout": {
			"contentSize": "40rem"
		}
	}
}
If you open a template in the Site Editor, you can use it to define the layout for various blocks. In the screenshot below, you can see that the Post Content block has the Inner blocks use content width option selected under the Layout tab:
What this setting does is tell WordPress that any nested blocks within the Post Content block should be set to the 
40rem value defined for 
settings.layout.contentSize in 
theme.json.
Wide Size
The 
settings.layout.wideSize property defines a width for “wide” blocks. To be useful, wide blocks must be nested within a block that is telling WordPress that its inner blocks should be limited to the “content” size. Wide-aligned blocks are meant to “break outside” of their parent block.
Not every theme will benefit by having a wide size. Depending on the design, a theme’s layout may simply not have additional room for blocks to break out of their container. In those cases, you do not need to set this value.
For theme designs that can accommodate wide blocks (typical of sidebar-less designs), you will want to set this to a value that is greater than 
settings.layout.contentWidth. But it shouldn’t stretch to the width of the full screen (e.g., 
100vw). WordPress has a separate full-width setting that you can use for that.
Try adding a custom 
settings.layout.wideSize to your 
theme.json file (remember, you need a set content size for this to be useful):
{
	"version": 2,
	"settings": {
		"layout": {
			"contentSize": "40rem",
			"wideSize": "64rem"
		}
	}
}
Now open your Site Editor in the WordPress admin and edit a template. First, add a Group block with the Inner blocks use content width option enabled. Then, stick another block within it and select the Wide width option.
In the screenshot below, you can see the Post Featured Image block nested within a Group block. It breaks out of its parent container but the other post-related blocks are limited to the content width:

Lightbox
settings.lightbox is a specific setting that you can enable for supported blocks. It enables a lightbox feature that expands an image when a site visitor clicks on an image.
This setting is only available as of WordPress 6.4 and is specific to the core Image block (
core/image).
Lightbox settings
The 
lightbox setting is specific to the Image block, so the following examples will be shown in that context.
The 
lightbox property is an object that has two nested properties that you can configure:
enabled: Whether to enable the lightbox feature for the Image block. The default value is 
undefined (the equivalent of being disabled).
allowEditing: Whether to show the Expand on click option in the interface, which allows the user to enable/disable lightbox for individual images. Defaults to 
true.
Here is a look at the default 
theme.json:
{
	"version": 2,
	"settings": {
		"blocks": {
			"core/image": {
				"lightbox": {
					"allowEditing": true
				}
			}
		}
	}
}
Enabling lightbox for images
To enable the lightbox feature for Image blocks used throughout the site, you must set 
settings.blocks.core/image.lightbox.enabled to true in 
theme.json:
{
	"version": 2,
	"settings": {
		"blocks": {
			"core/image": {
				"lightbox": {
					"enabled": true
				}
			}
		}
	}
}
On the front-end of the site, visitors will be able to expand the image when clicking on it. The image will then overlay the entire screen (including an x button for closing the overlay), as shown below:
Disabling user editing
By default, WordPress will show an Expand on Click option under the Settings tab for the Image block:
This control allows your theme’s users to enable or disable the lightbox feature on a per-block basis.
To disallow user editing, you must set 
settings.blocks.core/image.lightbox.allowEditing to 
false in 
theme.json:
{
	"version": 2,
	"settings": {
		"blocks": {
			"core/image": {
				"lightbox": {
					"allowEditing": false
				}
			}
		}
	}
}

Position
The 
settings.position property in 
theme.json gives you control over the global positioning settings for blocks in WordPress. It’s important to note that this lets you configure the available settings in the user interface, not the position styles.
Position settings
position is an object that’s nested directly within the top-level 
settings property in 
theme.json. Currently, it only lets you set a single property:
sticky: A boolean value for enabling block support for the Position: Sticky option.
Take a look at the 
position property in the context of a 
theme.json file with its default values:
{
	"version": 2,
	"settings": {
		"position": {
			"sticky": false
		}
	}
}
Enabling sticky positioning
Sticky positioning can be particularly useful in theme designs that feature a header that sticks to the top of the screen as the user scrolls down the page. This is one of the primary use cases, but it can also be useful in other scenarios.
Setting a block to the sticky position will stick the block to its most immediate parent when the user scrolls the page. Sticky positioning is only possible if enabled in 
theme.json.
To enable sticky positioning for blocks that support it, set 
settings.position.sticky to 
true:
{
	"version": 2,
	"settings": {
		"position": {
			"sticky": true
		}
	}
}
This will enable a new Position tab in the block inspector controls (for blocks that support the position feature, such as Group). The control will show a dropdown select with the available position options: Default and Sticky:
If you want to create a sticky header, note that you cannot use positioning on the Header template part. You must wrap it with a containing Group block and apply the sticky positioning to the Group.

Settings Reference
The document is a reference to the available settings properties that you can configure via the 
settings object in 
theme.json. Each of the settings has an in-depth guide on how to use it within the Settings documentation.
Appearance Tools
settings.appearanceTools is a top-level property with no sub-properties nested beneath it. It is documented at Settings: Appearance Tools.
Property
Type
Default
appearanceTools
boolean
false
Border
settings.border is an object that supports the nested properties listed in the below table. It is documented at Settings: Border.
Property
Type
Default
color
boolean
false
radius
boolean
false
style
boolean
false
width
boolean
false
Enabling any one of the 
color, 
style, or 
width settings will automatically enable the other two since the properties are linked together.
Color
settings.color is an object that supports the nested properties listed in the below table. It is documented at Settings: Color.
Property
Type
Default
Props
background
boolean
true
—
custom
boolean
true
—
customDuotone
boolean
true
—
customGradient
boolean
true
—
defaultDuotone
boolean
true
—
defaultGradients
boolean
true
—
defaultPalette
boolean
true
—
duotone
array 
array
colors, 
name, 
slug
gradients
array 
array
gradient, 
name, 
slug
link
boolean
false
—
palette
array 
array
color, 
name, 
slug
text
boolean
true
—
Custom
settings.custom is an object that supports any number of nested custom properties, as shown in the below table. It is documented at Settings: Custom.
Property
Type
Default
custom.<custom>
any
—
Dimensions
settings.dimensions is an object that supports the nested properties listed in the below table. It is documented at Settings: Dimensions.
Property
Type
Default
minHeight
boolean
false
Layout
settings.layout is an object that supports the nested properties listed in the below table. It is documented at Settings: Layout.
Property
Type
Default
contentSize
string
""
wideSize
string
""
Lightbox
settings.lightbox is an object that supports the nested properties listed in the below table. It is documented at Settings: Lightbox.
Property
Type
Default
allowEditing
boolean
true
enabled
boolean
false
This setting is only available as of WordPress 6.4 and is specific to the core Image block (
core/image).
Position
settings.position is an object that supports the nested properties listed in the below table. It is documented at Settings: Position.
Property
Type
Default
sticky
boolean
false
Shadow
settings.shadow is an object that supports the nested properties listed in the below table. It is documented at Settings: Shadow.
Property
Type
Default
Props
defaultPresets
boolean
true
presets
array 
array
name, 
shadow, 
slug
Spacing
settings.spacing is an object that supports the nested properties listed in the below table. It is documented at Settings: Spacing.
Property
Type
Default
Props
blockGap
boolean
null
null
customSpacingSize
boolean
true
—
margin
boolean
false
—
padding
boolean
false
—
spacingScale
object
object
operator, 
increment, 
steps, 
mediumStep, 
unit
spacingSizes
array 
array
name, 
size, 
slug
units
array 
[ "px", "em", "rem", "vh", "vw", "%" ]
—
Typography
settings.typography is an object that supports the nested properties listed in the below table. It is documented at Settings: Typography.
Property
Type
Default
Props
customFontSize
boolean
true
—
dropCap
boolean
true
—
fontFamilies
array 
array
fontFace, 
fontFamily, 
name, 
slug
fontSizes
array 
array
fluid, 
name, 
size, 
slug
fontStyle
boolean
true
—
fontWeight
boolean
true
—
fluid
boolean
false
—
letterSpacing
boolean
true
—
lineHeight
boolean
false
—
textColumns
boolean
false
—
textDecoration
boolean
true
—
textTransform
boolean
true
—
writingMode
boolean
false
—
Use Root Padding Aware Alignments
settings.useRootPaddingAwareAlignments is a top-level property with no sub-properties nested beneath it. It is documented at Settings: Use Root Padding Aware Alignments.
Property
Type
Default
useRootPaddingAwareAlignments
boolean
false
This setting works together with 
styles.spacing.padding in 
theme.json. If enabled, 
styles.spacing.padding must be an object that defines the 
top, 
right,  
bottom, and 
left styles separately.

Shadow
The 
settings.shadow property in 
theme.json currently lets you create custom shadow presets. As of WordPress 6.3, it contains no settings for enabling or disabling UI elements.
Shadow, in this case, refers specifically to the 
box-shadow CSS feature and is unrelated to 
text-shadow.
Shadow settings
The 
settings.shadow property contains two settings that you can configure:
defaultPresets: A boolean value for enabling or disabling the default WordPress shadow presets. Defaults to 
true.
presets: An array of objects for registering custom shadows for use in your theme or by users.
Here is a look at the default shadow property in 
theme.json:
{
	"version": 2,
	"settings": {
		"shadow": {
			"defaultPresets": true,
			"presets": [
				{
					"name": "Natural",
					"slug": "natural",
					"shadow": "6px 6px 9px rgba(0, 0, 0, 0.2)"
				},
				{
					"name": "Deep",
					"slug": "deep",
					"shadow": "12px 12px 50px rgba(0, 0, 0, 0.4)"
				},
				{
					"name": "Sharp",
					"slug": "sharp",
					"shadow": "6px 6px 0px rgba(0, 0, 0, 0.2)"
				},
				{
					"name": "Outlined",
					"slug": "outlined",
					"shadow": "6px 6px 0px -3px rgba(255, 255, 255, 1), 6px 6px rgba(0, 0, 0, 1)"
				},
				{
					"name": "Crisp",
					"slug": "crisp",
					"shadow": "6px 6px 0px rgba(0, 0, 0, 1)"
				}
			]
		}
	}
}
As you can see, WordPress registers several default presets that you can use directly in your block styles or that users can select from the interface:
Natural
Deep
Sharp
Outline
Crisp
Like all presets, WordPress will generate a CSS custom property for each registered shadow. Shadow presets are named 
--wp--preset--shadow--{$slug}.
Here is an example of the CSS generated for the default shadow presets:
body {
	--wp--preset--shadow--natural: 6px 6px 9px rgba(0, 0, 0, 0.2);
	--wp--preset--shadow--deep: 12px 12px 50px rgba(0, 0, 0, 0.4);
	--wp--preset--shadow--sharp: 6px 6px 0px rgba(0, 0, 0, 0.2);
	--wp--preset--shadow--outlined: 6px 6px 0px -3px rgba(255, 255, 255, 1), 6px 6px rgba(0, 0, 0, 1);
	--wp--preset--shadow--crisp: 6px 6px 0px rgba(0, 0, 0, 1);
}
Disabling core WordPress shadows
The default shadows available in core will not match the design of every theme. Typically, they will only work well for themes with a white or very light gray background. If your theme uses a different color, you will almost always want to remove these.
But there may be other reasons to disable the defaults. Perhaps you want to limit users to only the shadows that you’ve specifically designed for your theme or simply not like their design.
Whatever the reason, you can remove them by setting 
settings.shadow.defaultPresets to 
false in 
theme.json:
{
	"version": 2,
	"settings": {
		"shadow": {
			"defaultPresets": false
		}
	}
}
Adding custom shadow presets
WordPress lets you register any number of custom shadows. You can add them via the 
settings.shadow.presets property, which is an array used for storing shadow objects. Each object in this array should contain three values:
name: A human-readable name or label for the shadow that can be translated.
slug: A machine-readable slug for the shadow, which is used to build its associated CSS  custom property.
shadow: A valid CSS value for the 
box-shadow CSS property.
Try your hand at registering a few shadows of your own. You can use this 
theme.json code to get started, which contains several shadow examples:
{
	"$schema": "https://schemas.wp.org/trunk/theme.json",
	"version": 2,
	"settings": {
		"shadow": {
			"presets": [
				{
					"name": "Small",
					"slug": "sm",
					"shadow": "0 1px 2px 0 rgb(0 0 0 / 0.05)"
				},
				{
					"name": "Medium",
					"slug": "md",
					"shadow": "0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1)"
				},
				{
					"name": "Large",
					"slug": "lg",
					"shadow": "0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1)"
				},
				{
					"name": "XL",
					"slug": "xl",
					"shadow": "0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1)"
				},
				{
					"name": "2XL",
					"slug": "2-xl",
					"shadow": "0 20px 25px -5px rgb(0 0 0 / 0.1), 0 8px 10px -6px rgb(0 0 0 / 0.1)"
				},
				{
					"name": "Inner",
					"slug": "inner",
					"shadow": "inset 0 2px 4px 0 rgb(0 0 0 / 0.05)"
				}
			]
		}
	}
}
Currently, this only shows a shadow option for the core Button block in the user interface. This control can be accessed via  Appearance > Editor > Styles > Style Book in the WordPress admin. From there, select the Button block and locate the Shadow option in the Effects tab, as shown here:
It’s possible for third-party blocks to also utilize shadow presets and show them in the interface in the post, template, or site editors.
Like other presets, you can also use your custom shadows (or core WordPress shadows) in 
theme.json Styles.
For a deeper dive into this feature, read Using the box-shadow feature for themes on the WordPress Developer Blog.

Spacing
Spacing is one of the most complex parts of web design. It involves combining things like margin, padding, gap, line height, font size, and more into a harmonious flow. Doing this well requires a keen eye and a foundational understanding of how each of these pieces come together.
The 
settings.spacing property in 
theme.json covers settings related specifically to margin, padding, and gap.
This handbook also has documentation for typography settings and applying styles to blocks, both of which play roles in wrangling the spacing for your overall design.
Spacing settings
The 
settings.spacing object has several properties that you can configure:
blockGap: Whether to enable the Block Spacing option for blocks that support it. Can be a boolean value (
true/
false). Defaults to 
null. If set to null, WordPress’ generated CSS is also disabled.
margin:  Whether to enable the Margin option for supported blocks. Defaults to 
false.
padding: Whether to enable the Padding option for supported blocks. Defaults to 
false.
customSpacingSize: Whether to allow users to input custom spacing values for supported blocks. Defaults to 
true.
spacingScale: A configuration object for defining a custom spacing scale. WordPress defines a default scale with seven steps that increment by 
1.5rem.
spacingSizes: An array of custom size objects that may overrule the spacing scale or add to it.
units: An array of possible CSS units that users can select from when adding custom spacing.
Here is what spacing settings look like the default WordPress 
theme.json:
{
	"version": 2,
	"settings": {
		"spacing": {
			"blockGap": null,
			"customSpacingSize": true,
			"margin": false,
			"padding": false,
			"spacingScale": {
				"operator": "*",
				"increment": 1.5,
				"steps": 7,
				"mediumStep": 1.5,
				"unit": "rem"
			},
			"spacingSizes": [],
			"units": [ "px", "em", "rem", "vh", "vw", "%" ]
		}
	}
}
Enabling or disabling spacing options
As noted in the default settings in the previous section, there are several settings that are merely for enabling or disabling elements in the user interface. In this section, you will learn how to configure each of these.
Enabling block spacing (block gap)
In WordPress, the “block gap” refers to the spacing between blocks on a page. In most cases, this is the vertical spacing between blocks. But it can also refer to horizontal spacing when blocks are set in horizontal flex or in a grid layout.
In flow layouts (the default), the block gap is applied using the CSS 
margin-top property to sibling elements. In flex or grid layouts, it is applied using the CSS 
gap property.
WordPress will automatically output the CSS for the block gap if this setting is not disabled entirely (the default).
You will learn more about defining block gap styles in the Styles documentation, but having a baseline understanding of the terminology should help you decide how to work with this option.
The primary purpose of the 
settings.spacing.blockGap is to enable or disable the user interface for the Block Spacing control for blocks that support it. You can do this by setting it to 
true or 
false.
However, you can also leave it as 
null (the default value). This disables the user interface. In addition, it removes the WordPress-generated block spacing CSS.
Leaving this to the default 
null value is not usually recommended except in special cases. Generally, you would want consistent spacing as part of your design’s vertical rhythm. If set to 
null, you will need to handle that manually via custom CSS.
Use this table as a reference when determining which value to assign to 
settings.spacing.blockGap:
blockGap Value
Block Spacing Control
WordPress-generated CSS
null
No
No
true
Yes
Yes
false
No
Yes
Now try configuring the setting. Open your 
theme.json file and set the property to 
true:
{
	"version": 2,
	"settings": {
		"spacing": {
			"blockGap": true
		}
	}
}
For blocks that support the property, you should now see the Block Spacing control appear. Here is a screenshot of what that looks like on the Post Template block:
Because of the way the layout system works in WordPress, it will output CSS that is specific to individual containers to handle the gap between blocks nested within those containers. For the screenshot example, here’s what that CSS looks like:
.wp-container-17.wp-container-17 > :first-child:first-child {
	margin-block-start: 0;
}
	
.wp-container-17.wp-container-17 > * {
	margin-block-start: var(--wp--preset--spacing--plus-4);
	margin-block-end: 0;
}
Of course, the ID (
17) and value will be different on a case-by-case basis.
Enabling margin and padding
The margin and padding settings are a little more straightforward. They are both disabled by default, and you can enable them by setting their values to 
true in 
theme.json:
{
	"version": 2,
	"settings": {
		"spacing": {
			"margin": true,
			"padding": true
		}
	}
}
This will make the Margin and Padding controls appear for supported blocks in their inspector controls in the sidebar:
Of course, you are free to leave both of these to the default value of 
false or configure them to your liking.
Disabling user-defined spacing sizes
When any one of the 
blockGap, 
margin, or 
padding spacing settings are enabled, WordPress will output a user interface for setting those values for blocks that support them. By default, users can select from a list of preset spacing sizes (see “Spacing scale and sizes” below) or input a custom value.
In this screenshot, you can see that there is a custom Block Spacing setting chosen for the Buttons block:
You may want to limit users to your predefined spacing scale or sizes for your theme. This is often a good idea if you want to ensure consistent spacing throughout your design.
To do this, you must set the 
customSpacingSizes setting to 
false. This disables the custom spacing option in the editor UI but leaves the control for the theme’s defined sizes available:
{
	"version": 2,
	"settings": {
		"spacing": {
			"customSpacingSize": false
		}
	}
}
With custom spacing sizes disabled, the Block Spacing option from the Buttons block example will be limited to the theme’s preset sizes:
Defining allowed spacing units
If you choose to enable the 
settings.spacing.customSpacingSize option covered in the previous section, you will need to make another choice: which CSS unit values will your theme allow?
By default, WordPress lets users select from a subset of possible CSS units (there are dozens in the CSS specification). To choose which units you want to support, you must add them into the 
settings.spacing.units array in 
theme.json (shown with the defaults):
{
	"version": 2,
	"settings": {
		"spacing": {
			"units": [ "px", "em", "rem", "vh", "vw", "%" ]
		}
	}
}
The currently-allowed possible units that you can choose from are:
px
%
em
rem
vw
vh
vmin
vmax
ch
ex
cm
mm
in
pc
pt
As of WordPress 6.3, the allowed units are limited to the above list. There is an open ticket to expand these to support more modern units.
Spacing scale and sizes
One of the most important things that you should configure in your 
theme.json file is your spacing presets. WordPress will generate these presets as CSS custom properties, loading them in the editor and front end.
Most designers will use some type of standard scaling system for handling spacing, and WordPress gives you the flexibility to use whatever system you choose.
There are two methods for registering your spacing presets:
spacingScale: A generated scale based on your configuration values.
spacingSizes: Completely custom-defined spacing sizes.
Technically, you can use both of these methods, mixing and matching them. But it is generally recommended to choose one over the other for simplicity.
Spacing presets appear as choices for the Block Spacing, Margin, and Padding block controls (for blocks that support them). This means that you can present users with spacing options that are specific to your theme. You can also use these presets in the Styles section in your 
theme.json or custom CSS.
WordPress generates a default spacing scale, as shown in this table:
CSS Custom Property
CSS Value
Label
--wp-preset--spacing--20
0.44rem
2X-Small
--wp-preset--spacing--30
0.67rem
X-Small
--wp-preset--spacing--40
1rem
Small
--wp-preset--spacing--50
1.5rem
Medium
--wp-preset--spacing--60
2.25rem
Large
--wp-preset--spacing--70
3.38rem
X-Large
--wp-preset--spacing--80
5.06rem
2X-Large
It is unlikely that this scale matches your design. So you will want to choose a method for overriding these default values.
Custom spacing scale
WordPress allows theme authors to create a custom spacing scale by providing a set of configuration instructions. Each step in the scale generates a custom CSS property with the slug of 
--wp--preset--spacing--{step} (steps appear in increments of 10, regardless of their value).
The 
spacingScale object has five sub-settings that themes can configure:
operator: The operator used to increment the scale. The available options are 
+ (addition) and 
* (multiplication). The default value is 
*.
increment: A number in which to increment the scale by when used in conjunction with the 
operator setting. The default value is 
1.5.
steps: The total number of steps in the scale. The default value is 
7.
mediumStep: The medium value of the scale. The default value is 
1.5.
unit: A valid CSS spacing unit. The available options are 
px, 
em, 
rem, 
vh, 
vw, and 
%. The default value is 
rem.
The following example is a custom scale with seven steps that increments by 
0.25rem:
{
	"version": 2,
	"settings": {
		"spacing": {
			"spacingScale": {
				"operator": "+",
				"increment": 0.25,
				"steps": 7,
				"mediumStep": 1,
				"unit": "rem"
			}
		}
	}
}
As shown in the screenshot, you should see a range slider the Padding, Margin, and Block Spacing controls for setting your registered values:
When there are seven or fewer spacing presets, the interface will show a range slider for spacing controls. But more than seven displays a dropdown select. This applies to both the 
spacingScale method used here and the 
spacingSizes method in the next section.
This table represents your custom spacing scale (compare to the default scale to see how things have changed):
CSS Custom Property
CSS Value
Label
--wp-preset--spacing--20
0.25rem
2X-Small
--wp-preset--spacing--30
0.5rem
X-Small
--wp-preset--spacing--40
0.75rem
Small
--wp-preset--spacing--50
1rem
Medium
--wp-preset--spacing--60
1.25rem
Large
--wp-preset--spacing--70
1.5rem
X-Large
--wp-preset--spacing--80
1.75rem
2X-Large
The 
mediumStep value is always assigned to the 
--wp--preset--spacing--50 preset when WordPress generates the CSS, and the other preset slugs in the scale extend up/down from this middle number in increments of 10.
The spacing scale will never go below 
--wp--preset--spacing--10. For scales with more than 10 steps, the bottom end of the scale will not generate presets because the 
mediumStep is always set to 
--wp--preset--spacing--50.
Disable the spacing scale
If you want to disable WordPress’ spacing scale altogether, you can set 
steps to 
0 in 
theme.json:
{
	"version": 2,
	"settings": {
		"spacing": {
			"spacingScale": {
				"steps": 0
			}
		}
	}
}
This can be useful when choosing to register completely custom spacing sizes, as covered in the next section.
Custom spacing sizes
If you want more precise control over the spacing options, you can build out the individual spacing sizes instead of using the WordPress spacing scale system. This provides control over each option’s name, size, and slug.
The 
spacingSizes property lets you define an array of size objects. Each size object accepts three values:
name: The human-readable title for the size, which can be translated.
size: A valid CSS size. This can be a number and unit, a fluid size using 
clamp(), or a reference to another custom CSS property.
slug : The slug for the size, which will be appended to a generated CSS custom property: 
--wp--preset--spacing--{slug}.
The following is an example of creating a five-step scale that increments by 
0.25rem:
{
	"version": 2,
	"settings": {
		"spacing": {
			"spacingSizes": [
				{
					"name": "Step 1",
					"size": "0.25rem",
					"slug": "10"
				},
				{
					"name": "Step 2",
					"size": "0.5rem",
					"slug": "20"
				},
				{
					"name": "Step 3",
					"size": "0.75rem",
					"slug": "30"
				},
				{
					"name": "Step 4",
					"size": "1rem",
					"slug": "40"
				},
				{
					"name": "Step 5",
					"size": "1.25rem",
					"slug": "50"
				}
			]
		}
	}
}
You should see a range slider the Padding, Margin, and Block Spacing controls for setting your registered values, as shown here:
This table represents your custom spacing sizes:
CSS Custom Property
CSS Value
Label
--wp-preset--spacing--10
0.25rem
Step 1
--wp-preset--spacing--20
0.5rem
Step 2
--wp-preset--spacing--30
0.75rem
Step 3
--wp-preset--spacing--40
1rem
Step 4
--wp-preset--spacing--50
1.25rem
Step 5
Creating fluid sizes
If you want to use fluid spacing, you must use the 
settings.spacing.spacingSizes method for controlling the size presets.
To use fluid sizes, you merely need to add them as the 
size parameter for each of the size objects under 
settings.spacing.spacingSizes. 
clamp(), 
min(), 
max(), and other valid CSS values are supported.
Here is an example of a seven-step fluid spacing scale registered as individual sizes in 
theme.json:
{
	"version": 2,
	"settings": {
		"spacing": {
			"spacingSizes": [
				{
					"name": "Fluid Scale -3",
					"size": "clamp( 0.31rem, 0.11vw + 0.28rem,  0.35rem )",
					"slug": "minus-3"
				},
				{
					"name": "Fluid Scale -2",
					"size": "clamp( 0.47rem, 0.16vw + 0.42rem,  0.53rem )",
					"slug": "minus-2"
				},
				{
					"name": "Fluid Scale -1",
					"size": "clamp( 0.71rem, 0.25vw + 0.63rem,  0.79rem )",
					"slug": "minus-1"
				},
				{
					"name": "Fluid Scale +/- 0 (Base)",
					"size": "clamp( 1.06rem, 0.37vw + 0.95rem,  1.19rem )",
					"slug": "base"
				},
				{
					"name": "Fluid Scale +1",
					"size": "clamp( 1.20rem, 0.85vw + 0.94rem,  1.48rem )",
					"slug": "plus-1"
				},
				{
					"name": "Fluid Scale +2",
					"size": "clamp( 1.34rem, 1.5vw + 0.89rem,  1.86rem )",
					"slug": "plus-2"
				},
				{
					"name": "Fluid Scale +3",
					"size": "clamp( 1.86rem, 3.7vw + -0.05rem,  2.32rem )",
					"slug": "plus-3"
				}
			]
		}
	}
}
This results in the following values, as shown in this table:
CSS Custom Property
CSS Value
Label
--wp-preset--spacing--minus-1
clamp( 0.31rem, 0.11vw + 0.28rem,  0.35rem )
Fluid Scale -3
--wp-preset--spacing--minus-2
clamp( 0.47rem, 0.16vw + 0.42rem,  0.53rem )
Fluid Scale -2
--wp-preset--spacing--minus-3
clamp( 0.71rem, 0.25vw + 0.63rem,  0.79rem )
Fluid Scale -1
--wp-preset--spacing--base
clamp( 1.06rem, 0.37vw + 0.95rem,  1.19rem )
Fluid Scale +/- 0 (Base)
--wp-preset--spacing--plus-1
clamp( 1.20rem, 0.85vw + 0.94rem,  1.48rem )
Fluid Scale +1
--wp-preset--spacing--plus-2
clamp( 1.34rem, 1.5vw + 0.89rem,  1.86rem )
Fluid Scale +2
--wp-preset--spacing--plus-3
clamp( 1.86rem, 3.7vw + -0.05rem,  2.32rem )
Fluid Scale +3

Typography
Typography is a wide-ranging subject in web design, and no single piece of documentation could do it justice. There are book-length works that dive into the finer details and articles aplenty across the web that teach best practices, tips, and tricks at length.
This guide will specifically get you up to speed with the available settings available via 
settings.typography in 
theme.json.
Typography is also tightly related to spacing in your theme, so you will need to familiarize yourself with the spacing settings to get the most out of both guides. You will also take what you learn from this documentation and apply it to your 
theme.json styles.
Enabling and disabling typography options
There are several settings that are merely for enabling or disabling elements in the user interface. Each of these properties accept a boolean value, meaning that you can set them to either 
true or 
false.
Not every block will support every typography setting. Some are specific to a single block. For example, the 
dropCap property only works for Paragraph blocks. Others are widely used by almost any block with text, such as 
customFontSize.
These 
settings.typography properties let you enable or disable features in the interface:
customFontSize: Whether to let users input custom font sizes. Defaults to 
true.
dropCap: Whether users can enable a drop-cap for the first letter of the Paragraph block. Defaults to 
true.
fontStyle: Whether users can select a custom font style. Defaults to 
true.
fontWeight: Whether users can select a custom font weight. Weight ranges map to the standard Thin through Black font weights. Defaults to 
true.
letterSpacing: Whether users can input a custom letter spacing value. Defaults to 
false.
lineHeight: Whether users can input a custom line height for text. There is no way to register line-height presets, so this option enables a completely custom input. Defaults to 
false.
textColumns: Whether to show a columns option for the block’s text. Defaults to 
false.
textDecoration: Whether the user can set the text decoration for a block’s text. The available options are None, Underline, and Strikethrough. Defaults to 
true.
textTransform: Whether the user can change the letter case for a block’s text. The available options are None, Uppercase, Lowercase, and Capitalize. Defaults to 
true.
writingMode: Whether to enable the text Orientation in the interface, allowing users to choose between Horizontal and Vertical text. Defaults to 
false.
Here is what these typography settings look like in the default WordPress 
theme.json:
{
	"version": 2,
	"settings": {
		"typography": {
			"customFontSize": true,
			"dropCap": true,
			"fontStyle": true,
			"fontWeight": true,
			"letterSpacing": true,
			"lineHeight": false,
			"textColumns": false,
			"textDecoration": true,
			"textTransform": true,
			"writingMode": false
		}
	}
}
In this screenshot, take note of the Typography panel for the Paragraph block, which has every setting enabled:
Depending on your theme’s audience, you will want to enable only the features that its users will need. For example, you may have a client who only needs to configure the font size. It wouldn’t make sense to show them every setting if it gets in the way of their workflow.
A note on drop caps: the current implementation feature is notoriously buggy with different font families, font sizes, and line heights. If you leave this feature enabled, be sure that you test that drop caps look good within your theme’s design. You may need to add custom CSS so that it matches your theme.
Custom font families
WordPress lets you register as many font families as you want via the 
settings.typography.fontFamilies property in 
theme.json. You can add support for both system fonts (those that live on the visitor’s computer) or web fonts (custom fonts bundled with your theme). You’ll learn how to register both of these in this section.
These appear as options under the Typography > Font field in the inspector panel for blocks that support selecting a font:
The 
settings.typography.fontFamilies property is an empty array by default. You can register fonts by passing in font family objects with these properties:
name: (Required) The human-readable title for the font family, which can be translated.
slug: (Required) The slug for the font family, which will be appended to a generated CSS custom property: 
--wp--preset--font-family--{slug}.
fontFamily: (Required) A valid value that will map to the CSS 
font-family value. Generally, this will be a font stack (a list of families that the browser will try to use in order).
fontFace: (Optional) An array of font faces that are mapped to the 
@font-face CSS at-rule. You only need to use this when bundling custom web fonts with your theme.
Here is what the font family setting looks like in the default WordPress 
theme.json:
{
	"version": 2,
	"settings": {
		"typography": {
			"fontFamilies": []
		}
	}
}
In the following subsections, you will first learn how to register system fonts. Then, you will take the next step and register a custom web font.
Registering system fonts
System fonts are more straightforward than web fonts. You only need to know which fonts you want to use. For this exercise, let’s assume that you want to register two fonts that you will use in your theme:
Primary: a transitional serif font stack that will look good across modern devices.
Secondary: the user’s system UI font.
Add this code to your 
theme.json to register each of the fonts:
{
	"$schema": "https://schemas.wp.org/trunk/theme.json",
	"version": 2,
	"settings": {
		"typography": {
			"fontFamilies": [
				{
					"name": "Primary",
					"slug": "primary",
					"fontFamily": "Charter, 'Bitstream Charter', 'Sitka Text', Cambria, serif"
				},
				{
					"name": "Secondary",
					"slug": "secondary",
					"fontFamily": "system-ui, sans-serif"
				}
			]
		}
	}
}
These options will now appear in the Typography > Font dropdown for any blocks that support the feature.
WordPress will also generate two CSS custom properties with the 
--wp--preset--font-family--{$slug} format in both the editor and on the front end:
body {
	--wp--preset--font-family--primary: Charter, 'Bitstream Charter', 'Sitka Text', Cambria, serif;
	--wp--preset--font-family--secondary: system-ui, sans-serif;
}
You can reference these as 
var:preset|font-family|$slug when you begin using them as Styles in 
theme.json. You can also reference them using 
var( --wp--preset--font-family--{$slug} ) directly in CSS.
It is generally recommended to use a semantic naming scheme for your font family slugs so that they are more future proof when switching between child themes, style variations, and even from theme to theme. These examples use 
primary and 
secondary since those are widely used terms. It’s best to avoid naming your slugs so that they match the current font family.
Registering web fonts (font faces)
Registering custom web fonts works in much the same way as system fonts. The big difference is that you need to add the 
fontFace property to your font family objects.
fontFace must be an array of font face objects. Each object accepts these properties that map to descriptors for the 
@font-face CSS at-rule:
fontFamily: A valid CSS 
font-family descriptor.
fontWeight: A range of CSS 
font-weight values.
fontStyle: A valid CSS 
font-style value.
fontStretch: A valid CSS font stretch value.
src: An array of font file URLs where the font files are located (this can be used to support multiple formats, but only one is required).
The 
src property is unique in that it allows you to reference a URL that is relative to the 
theme.json file in your theme. Use the 
"file:./path/to/file.ext" format to reference a font bundled with your theme.
Let’s try an example. Building off the code from the previous section, suppose you wanted to replace the system UI font with the Open Sans web font.
This example will also assume you have downloaded and converted the Open Sans font to the modern 
.woff2 format, which is widely supported by most browsers. You’ve also placed these files in your theme’s 
/assets/fonts folder like this:
/assets
/fonts
/open-sans.woff2
/open-sans-italic.woff2
With your web fonts bundled in your theme and ready to go, add this code to your 
theme.json file to register them:
{
	"$schema": "https://schemas.wp.org/trunk/theme.json",
	"version": 2,
	"settings": {
		"typography": {
			"fontFamilies": [
				{
					"name": "Primary",
					"slug": "primary",
					"fontFamily": "Charter, 'Bitstream Charter', 'Sitka Text', Cambria, serif"
				},
				{
					"name": "Secondary",
					"slug": "secondary",
					"fontFamily": "'Open Sans', sans-serif",
					"fontFace": [
						{
							"fontFamily": "Open Sans",
							"fontWeight": "300 800",
							"fontStyle": "normal",
							"fontStretch": "normal",
							"src": [ "file:./assets/fonts/open-sans.woff2" ]
						},
						{
							"fontFamily": "Open Sans",
							"fontWeight": "300 800",
							"fontStyle": "italic",
							"fontStretch": "normal",
							"src": [ "file:./assets/fonts/open-sans-italic.woff2" ]
						}
					]
				}
			]
		}
	}
}
Like with system fonts, WordPress will generate CSS custom properties for web fonts. Here is what the CSS output looks like:
body {
	--wp--preset--font-family--primary: Charter, 'Bitstream Charter', 'Sitka Text', Cambria, serif;
	--wp--preset--font-family--secondary: 'Open Sans', sans-serif;
}
Custom font sizes
WordPress lets you register any number of preset font sizes that your theme users can choose from. By registering custom sizes, you can more easily maintain consistent typography across the theme.
Custom font sizes appear as options in the Typography > Size panel in the inspector controls for blocks that support the feature:
Note that if you have more than five custom sizes, the UI will show a dropdown select instead of the button group shown in the above screenshot.
There are two 
theme.json.settings.typography sub-properties related font sizes:
fluid: Whether to enable fluid font sizes that scale up on large screens and down on smaller screens. This can be overridden for individual custom sizes. Defaults to 
false.
fontSizes: An array of font size objects that you can use to customize the available presets that users can choose from. WordPress registers the default sizes of 
small, 
medium, 
large, and 
x-large.
Here is what these properties look like in the default WordPress 
theme.json:
{
	"version": 2,
	"settings": {
		"typography": {
			"fluid": false,
			"fontSizes": [
				{
					"name": "Small",
					"slug": "small",
					"size": "13px"
				},
				{
					"name": "Medium",
					"slug": "medium",
					"size": "20px"
				},
				{
					"name": "Large",
					"slug": "large",
					"size": "36px"
				},
				{
					"name": "Extra Large",
					"slug": "x-large",
					"size": "42px"
				}
			]
		}
	}
}
As you can see, WordPress disables fluid font sizes by default and registers four static sizes of its own. In almost all cases, you will want to overwrite these with sizes that match your theme’s design.
Like other presets that you can set in 
theme.json, WordPress automatically generates CSS custom properties for font sizes using the 
--wp--preset--font-size--{$slug} format. For the default sizes, this CSS is output in the editor and on the front end:
body {
	--wp--preset--font-size--small: 13px;
	--wp--preset--font-size--medium: 20px;
	--wp--preset--font-size--large: 36px;
	--wp--preset--font-size--x-large: 42px;
}
WordPress also generates custom CSS classes for each font size preset using the 
.has-{$slug}-font-size naming scheme. The default sizes produce these classes:
.has-small-font-size{
	font-size: var(--wp--preset--font-size--small) !important;
}
.has-medium-font-size{
	font-size: var(--wp--preset--font-size--medium) !important;
}
.has-large-font-size{
	font-size: var(--wp--preset--font-size--large) !important;
}
.has-x-large-font-size{
	font-size: var(--wp--preset--font-size--x-large) !important;
}
Enabling fluid typography
In modern web design, you will almost always utilize fluid typography. This allows your font sizes to scale up or down with the viewport or container.
WordPress uses a viewport-based system for fluid typography. But you don’t have to rely on this if you prefer to use something different, such as a container-based system, and can leave it disabled.
Suppose you wanted to use the default core sizes but wanted them all to be fluid instead of static values. You can enable this by setting 
settings.typography.fluid to 
true in your 
theme.json file:
{
	"version": 2,
	"settings": {
		"typography": {
			"fluid": true
		}
	}
}
WordPress will now generate fluid sizes for registered font sizes:
body {
	--wp--preset--font-size--small: 13px;
	--wp--preset--font-size--medium: clamp(14px, 0.875rem + ((1vw - 3.2px) * 0.852), 20px);
	--wp--preset--font-size--large: clamp(22.041px, 1.378rem + ((1vw - 3.2px) * 1.983), 36px);
	--wp--preset--font-size--x-large: clamp(25.014px, 1.563rem + ((1vw - 3.2px) * 2.413), 42px);
}
14px is the default minimum font-size limit. Because the 
small size is below that limit, it remained at its static size of 
13px.
Registering custom font size presets
You will undoubtedly want to register font sizes that match your theme’s design instead of sticking with the defaults. To do this, you must pass an array of font size objects to the 
settings.typography.fontSizes property in 
theme.json.
Each of these objects accepts several properties:
name: The human-readable title for the size, which can be translated.
size: A valid CSS size. This can be a number and unit, a custom fluid size using 
clamp(), or a reference to another custom CSS property.
slug: The slug for the size, which will be appended to a generated CSS custom property: 
--wp--preset--spacing--{slug}.
fluid: A boolean value to enable or disable fluid typography for this specific size, overwriting the global property. Alternatively, it can be an object containing:
min: The minimum value that the font size can scale down to. Must be a valid CSS size.
max: The maximum value that the font size can scale up to. Must be a valid CSS size.
Let’s register a simple set of custom sizes with static values first. Add this code to your 
theme.json file:
{
	"$schema": "https://schemas.wp.org/trunk/theme.json",
	"version": 2,
	"settings": {
		"typography": {
			"fontSizes": [
				{
					"name": "Small",
					"size": "1rem",
					"slug": "sm"
				},
				{
					"name": "Medium",
					"size": "1.25rem",
					"slug": "md"
				},
				{
					"name": "Large",
					"size": "1.5rem",
					"slug": "lg"
				}
			]
		}
	}
}
Just like with the default size presets, WordPress will automatically generate the CSS for each in both the editor and on the front end:
body {
	--wp--preset--font-size--sm: 1rem;
	--wp--preset--font-size--md: 1.25rem;
	--wp--preset--font-size--lg: 1.5rem;
}
Now, let’s take this one step further. In the previous example, you registered Small, Medium, and Large sizes. Suppose that you wanted the Small size to maintain its value regardless of the browser’s viewport width. But you want the Medium and Large size to scale along with the viewport.
Using the 
fluid property, let’s configure these on a size-by-size basis. Add this code to your 
theme.json:
{
	"$schema": "https://schemas.wp.org/trunk/theme.json",
	"version": 2,
	"settings": {
		"typography": {
			"fluid": true,
			"fontSizes": [
				{
					"name": "Small",
					"size": "1rem",
					"slug": "sm",
					"fluid": false
				},
				{
					"name": "Medium",
					"size": "1.25rem",
					"slug": "md",
					"fluid": {
						"min": "1rem",
						"max": "1.5rem"
					}
				},
				{
					"name": "Large",
					"size": "1.5rem",
					"slug": "lg",
					"fluid": {
						"min": "1.25rem",
						"max": "2rem"
					}
				}
			]
		}
	}
}
WordPress will generate these CSS custom properties:
body {
	--wp--preset--font-size--sm: 1rem;
	--wp--preset--font-size--md: clamp(1rem, 1rem + ((1vw - 0.2rem) * 1.136), 1.5rem);
	--wp--preset--font-size--lg: clamp(1.25rem, 1.25rem + ((1vw - 0.2rem) * 1.705), 2rem);
}
There aren’t many limits to how you can customize this for your theme. The above offers an intro to registering custom font sizes, but you have full control over how this works for your theme.
For a deeper understanding of fluid font sizes, read Intrinsic design, theming, and rethinking how to design with WordPress on the Developer Blog.

Use Root Padding Aware Alignments
The 
settings.useRootPaddingAwareAlignments property can be one of the most confusing settings in 
theme.json. It is not tied to an interface option. Nor is it used for registering presets. Instead, it’s for configuring where WordPress places your theme’s horizontal padding styles.
This means it works in conjunction with 
styles.spacing.padding in 
theme.json. You can find out more about general styling in the Styles documentation, but you’ll learn how this specific style works alongside this setting here.
What is root padding?
Before understanding how the 
settings.useRootPaddingAwareAlignments property works, you must first understand what root padding is.
Root padding is the padding that is applied to a web page’s “root” element. In the case of WordPress themes, this is the 
<body> element. To customize the spacing for the root element, you must target the 
styles.spacing.padding element in 
theme.json.
Take the following 
theme.json snippet, for example. It adds 
0 for top and bottom padding and 
2rem for left and right padding:
{
	"version": 2,	
	"styles": {
		"spacing": {
			"padding": {
				"top": "0",
				"bottom": "0",
				"left": "2rem",
				"right": "2rem"
			}
		}
	}
}
By default, this will add 
2rem of padding on the left and right sides of the 
<body> (root) element.
As shown in this screenshot, there is horizontal padding at the root, and a full-width Cover block stretches until it hits that padding:
This is the CSS that WordPress outputs based on the above 
theme.json code:
body {
	padding-top: 0;
	padding-right: 2rem;
	padding-bottom: 0;
	padding-left: 2rem;
}
But—and this is where things can look odd to seasoned designers—when 
settings.useRootPaddingAwareAlignments is enabled, the “root” padding is no longer applied to the root element. It is applied to container blocks like Group.
You’ll learn more about why this happens in the next section. The main goal right now is to understand that root padding is traditionally applied to the 
<body> element, and that is what most theme authors would expect.
For root padding aware alignments, WordPress is only concerned with the horizontal (left and right) padding. So the vertical (top and bottom) padding is not relevant to this documentation.
Enabling root padding aware alignments
By default, WordPress will apply root padding to the 
<body> element. If this makes sense for your theme’s design, you don’t need to do anything else.
But what if you want to let full-width items stretch to the edges of the screen and have padding on the root element?
When compared to the first screenshot, notice how the Cover block stretches to edges of the screen but there is padding still applied to the nested blocks here:
This is a common design pattern, and there are several ways to stretch elements beyond their containers in CSS. But WordPress has a standard approach that would work with any theme.
That’s where 
settings.useRootPaddingAwareAlignments comes in. When this property is set to 
true, it puts the root padding on container elements instead of 
<body>. This must also be combined with a 
styles.spacing.padding object, particularly with horizontal padding applied.
Try this code in your 
theme.json:
{
	"version": 2,
	"settings": {
		"useRootPaddingAwareAlignments": true
	},	
	"styles": {
		"spacing": {
			"padding": {
				"top": "0",
				"bottom": "0",
				"left": "2rem",
				"right": "2rem"
			}
		}
	}
}
There is no right or wrong way to handle root padding. It is a situational setting where you must decide which option is best for your theme’s design.
How does this work?
It’s not particularly vital to know how WordPress handles all of this under the hood, but sometimes you might just want a deeper understanding of what’s going on.
When you enable 
settings.useRootPaddingAwareAlignments, as shown in the last 
theme.json example, WordPress will generate two new bits of CSS. The first is that it defines some CSS custom properties for the root padding:
body {
	--wp--style--root--padding-top: 0;
	--wp--style--root--padding-right: 2rem;
	--wp--style--root--padding-bottom: 0;
	--wp--style--root--padding-left: 2rem;
}
The second is that it adds a 
.has-global-padding class:
.has-global-padding {
	padding-right: var(--wp--style--root--padding-right);
	padding-left: var(--wp--style--root--padding-left);
}
This class is then given to container blocks with constrained layouts (for example, Group blocks with the Layout > Inner blocks use content width option enabled):
<div class="wp-block-group has-global-padding is-layout-constrained wp-block-group-is-layout-constrained">
	<!-- nested blocks... -->
</div>
Beyond that, WordPress adds inline CSS to stretch nested wide and full-width blocks beyond their parent block’s width (including the additional padding that’s added to the width).

Applying Styles
Traditionally, theme authors would style everything from a stylesheet—and they still sometimes must. In modern WordPress, you can also style most, if not all, of your theme directly from your 
theme.json file.
When you use this standard system, it is also reflected in the Appearance > Editor > Styles interface. This means your theme’s users with access to that admin screen can also make changes that easily work alongside your theme’s styles. But it also means that you can design your theme directly from this visual interface if you choose to do so.
theme.json supports styles at three different levels:
Root (global)
Elements
Blocks
In this document, you will learn the syntax necessary for styling each of these things via JSON.
Styling the root element
When referring to the “root” element in WordPress themes, we’re specifically talking about the HTML 
<body> tag. It’s the root of the visual output for the page.
Technically, when styling the root element, you are adding global styles that trickle down through the design and are used unless a more specific element or block style overrides them. For example, you’ll likely want to set a default font-family or font-size that is used across the entire design. But you’ll, of course, want to change that in specific instances.
Because these are global styles, it means that they belong directly under the 
styles property.
So let’s add a default text and background color to show how this works:
{
	"version": 2,
	"styles": {
		"color": {
			"text": "#000000",
			"background": "#f5f1ea"
		}
	}
}
As you can see, the 
color property is nested directly beneath the 
styles property. This means that the 
text and 
background colors are applied directly to the 
<body> element by WordPress, resulting in this CSS in the editor and on the front end:
body {
	background: #f5f1ea;
	color: #000000;
}
And because of the way the cascade works in CSS, these colors will be used for everything, unless a more specific style rule overwrites it.
If you open your site on the front end or via Appearance > Editor in the WordPress admin, you should see your colors applied:
You are not just limited to colors. You can add 
typography, 
spacing, and more here. The root element supports almost all of the available style properties, which you can reference in the Supported Styles documentation.
The 
styles.spacing.padding property has a unique use case when used in conjunction with 
settings.useRootPaddingAwareAlignments. For more information on how these two work together, read the Use Root Padding Aware Alignments documentation.
Styling elements
WordPress has a standard system for styling elements via 
theme.json. In this case, “elements” usually maps to actual HTML elements. But there are cases where it’s referring to something that doesn’t map directly to a single HTML element. In general, these should be reasonably straightforward.
Just like styling the root element and blocks, which you’ll learn about below, you can apply a wide range of the supported styles to elements.
The currently-supported elements are:
button: Applied to 
<button> elements and button-like links, such as that used for the Button block.
caption: Applied to media captions, which are wrapped in a 
<figcaption> element.
cite: Applied to the 
<cite> element when used for citations, such as that used for the Quote and Pullquote blocks.
heading: Applied to all heading elements from 
<h1> through 
<h6>, but these can be overridden for individual headings.
h1 - h6: Each of the 
<h1> through 
<h6> elements can be individually styled.
link: Applied to the 
<a> tag, which is used to create links.
Let’s try a real example now. Suppose you wanted to give all buttons across the site a white text color that sits atop a red background. You need to target the 
text and 
background properties of 
styles.elements.button.color.
Add this code to your 
theme.json file:
{
	"version": 2,
	"styles": {
		"elements": {
			"button": {
				"color": {
					"text": "#ffffff",
					"background": "#aa3f33"
				}
			}
		}
	}
}
If you view a button in the Site Editor or on the front end of the site, you should see these colors applied:
Some elements both serve as element styles and the foundation of more specific blocks. In the case of elements that also tie into blocks, the block styles will overrule the element styles. For example, the Button and Heading blocks can have their own styles but they will fall back to the 
button and 
heading element styles.
WordPress will generate this CSS in both the editor and on the front end for your 
button element styles:
.wp-element-button, 
.wp-block-button__link {
	background-color: #aa3f33;
	color: #ffffff;
}
WordPress sometimes—but not always—gives elements a specific CSS class with the naming scheme of 
.wp-element-{$element}. For example, button elements have the 
.wp-element-button class. The styles you provide via 
theme.json are then applied to that CSS class.
As you can see in the generated CSS, WordPress is targeting the 
.wp-element-button class when styling the 
button element. But it’s also specifically targeting the 
.wp-block-button__link class for backward compatibility with the Button block.
Styling pseudo-classes
You can also add style properties for a standard set of CSS pseudo-classes for some elements. Generally, this will be for features like link hover and focus styles.
The 
button and 
link elements support these pseudo-classes:
:hover
:focus
:active
:visited
Each pseudo-class must be added as a property nested under the element you want to style. For example, you must target 
styles.elements.link.:hover to customize link hover styles.
Let’s look at this in context using the previous example of styling 
button elements. Suppose you wanted to change the background color when a user’s mouse hovers over buttons. Use this 
theme.json code to achieve that:
{
	"version": 2,
	"styles": {
		"elements": {
			"button": {
				"color": {
					"text": "#ffffff",
					"background": "#aa3f33"
				},
				":hover": {
					"color": {
						"background": "#822f27"
					}
				}
			}
		}
	}
}
Styling blocks
One of the great things about the block system is that it provides a standardized system for styling any block. This means that you can add styles for core WordPress blocks as well as third-party plugin blocks directly in 
theme.json.
To style a specific block, you must target 
styles.blocks.blockname in your 
theme.json file. From there, you can add any of the block’s supported styles.
Let’s take a look at a basic example. Assume that you want to give a slightly rounded border to all Image blocks. For this, you need to target the 
border.radius property.
Add this code to your 
theme.json file:
{
	"version": 2,
	"styles": {
		"blocks": {
			"core/image": {
				"border": {
					"radius": "6px"
				}
			}
		}
	}
}
This should make any instance of the Image block on your site appear with a rounded border:
WordPress will also generate this CSS for the nested 
<img> element within the Image block for both the editor and front end:
.wp-block-image img {
	border-radius: 6px;
}
You can add styles for as many or as few blocks as you want. That’s entirely up to you and what you want to accomplish with your design. Have fun with it!
For a full list of core WordPress blocks that you can style, visit the Core Blocks Reference. Note that this does not include blocks from plugins and other third-party sources.
When targeting a block’s styles, you must know both its namespace and slug. Above, you learned that the Image block has the namespace (
core) and slug (
image), creating the namespace/slug combination of 
core/image. All core WordPress blocks have the 
core namespace, and you can find this information for any block (including from third-party plugins) in its 
block.json file.
Styling elements nested in blocks
You can also add custom styles for elements that are nested within blocks. This feature gives you a lot of flexibility for contextually styling elements directly within 
theme.json.
When styling a block’s nested elements, you must pass an 
elements object directly under the block property: 
styles.blocks.blockname.elements.
Suppose you wanted a large font size for the PullQuote block but you wanted to create a fluid size for its nested 
<cite> element that never grew larger than 
50% of the parent block or 
1.5rem, whichever is the larger of the two.
For this, you need to define the 
typography.fontSize for both the 
core/pullquote block and its nested 
cite element in 
theme.json:
{
	"version": 2,
	"styles": {
		"elements": {
			"core/pullquote": {
				"typography": {
					"fontSize": "2.25rem"
				},
				"elements": {
					"cite": {
						"typography": {
							"fontSize": "max( 50%, 1.5rem )"
						}
					}
				}
			}
		}
	}
}
The font-size will now look like this in the editor:
WordPress generates this CSS for styling both the Pullquote block and its nested 
<cite> element:
.wp-block-pullquote {
	font-size: 2.25rem;
}
.wp-block-pullquote cite {
	font-size: max( 50%, 1.5rem );
}
Styling block style variations (block styles)
Since WordPress 6.2, you can customize the core block style variations (i.e., block styles) via 
theme.json. This feature allows you to use supported styles without having to write custom CSS in a separate stylesheet.
To customize a block style variation, you must add a nested 
variations property within the block you want to style in 
theme.json. Then, each variation can use any of the block’s supported styles.
Let’s walk through an example of modifying the Button block’s Outline style variation. Suppose you wanted to define the border color, style, and width that is specific to this block style variation.
Add this code to your 
theme.json:
{
	"version": 2,
	"styles": {
		"blocks": {
			"core/button": {
				"variations": {
					"outline": {
						"border": {
							"color": "currentColor",
							"style": "solid",
							"width": "2px"
						}
					}
				}
			}
		}
	}
}
You should now see these changes reflected in the editor when the Outline block style variation is selected for the Button block:
The currently available blocks and their core WordPress style variations are:
core/button: 
outline, 
fill
core/image: 
rounded
core/quote: 
plain
core/site-logo: 
rounded
core/separator: 
wide, 
dots
core/social-links: 
logos-only, 
pill-shape
core/table: 
stripes
core/tag-cloud: 
outline
For a deeper dive into customizing block style variations, check out Customizing core block style variations via theme.json on the WordPress Developer Blog.
Custom block style variations are not currently supported in 
theme.json. There is an open ticket for the feature. For now, you are limited to the core block style variations.

Styles Reference
This is a reference to the available style properties that you can apply to the root element (global), individual elements, and individual blocks in 
theme.json. Please review the Applying Styles documentation to learn how to apply styles to your theme.
Border
There are two methods for working with the 
border style property. The first is to target all sides of a block or element with the properties shown in the table:
Property
Type
CSS Property
border.radius
string, object
border-radius
border.color
string, object
border-color
border.style
string, object
border-style
border.width
string, object
border-width
Example usage in 
theme.json:
{
	"version": 2,
	"styles": {
		"border": {
			"color": "#000000",
			"style": "solid",
			"width": "1px"
		}
	}
}
The second method is to specifically target the 
top, 
right, 
bottom, and 
left sides:
Property
Type
CSS Property
border.<side>.color
string, object
border-<side>-color
border.<side>.style
string, object
border-<side>-style
border.<side>.width
string, object
border-<side>-width
Example usage in 
theme.json:
{
	"version": 2,
	"styles": {
		"border": {
			"top": {
				"color": "#000000",
				"style": "solid",
				"width": "1px"
			}
		}
	}
}
Color
The 
color style property lets you define the default text, background, and link colors for a block or element:
Property
Type
CSS Property
color.text
string, object
color
color.background-color
string, object
background-color
color.link
string, object
color (applied to nested 
<a> elements)
Example usage in 
theme.json:
{
	"version": 2,
	"styles": {
		"blocks": {
			"core/group": {
				"color": {
					"text": "#000000",
					"background": "#ffffff",
					"link": "#777777"
				}
			}
		}
	}
}
Dimensions
The 
dimensions style property lets you define the minimum height for a block or element:
Property
Type
CSS Property
dimensions.minHeight
string, object
min-height
Example usage in 
theme.json:
{
	"version": 2,
	"styles": {
		"blocks": {
			"core/cover": {
				"dimensions": {
					"minHeight": "50vh"
				}
			}
		}
	}
}
Filter
The 
filter style property lets you define filters for a block or element. Currently, you can set a default duotone filter:
Property
Type
CSS Property
filter.duotone
string, object
filter
Example usage in 
theme.json:
{
	"version": 2,
	"styles": {
		"blocks": {
			"core/image": {
				"filter": {
					"duotone": "var(--wp--preset--duotone--default-filter)"
				}
			}
		}
	}
}
Shadow
The 
shadow style property lets you define the default box-shadow style for a block or element:
Property
Type
CSS Property
shadow
string, object
box-shadow
Example usage in 
theme.json:
{
	"version": 2,
	"styles": {
		"blocks": {
			"core/heading": {
				"shadow": "0 1px 2px 0 rgb(0 0 0 / 0.05)"
			}
		}
	}
}
Spacing
The 
spacing style property lets you define the default gap, margin, and padding for a block or element:
Property
Type
CSS Property
blockGap
string, object
margin-top, 
gap
margin.<side>
string, object
margin-<side>
padding.<side>
string, object
padding-<side>
You can define any or all of the sides (
top, 
right, 
bottom, 
left) for the 
margin and 
padding style properties.
Example usage in 
theme.json:
{
	"version": 2,
	"styles": {
		"spacing": {
			"blockGap": "2rem",
			"margin": {
				"top": "2rem",
				"bottom": "2rem"
			},
			"padding": {
				"left": "2rem",
				"right": "2rem"
			}
		}
	}
}
Typography
The 
typography style property lets you define default font and text-related styles for a block or element:
Property
Type
CSS Property
fontFamily
string, object
font-family
fontSize
string, object
font-size
fontStyle
string, object
font-style
fontWeight
string, object
font-weight
letterSpacing
string, object
letter-spacing
lineHeight
string, object
line-height
textColumns
string
columns
textDecoration
string, object
text-decoration
writingMode
string, object
writing-mode
Example usage in 
theme.json:
{
	"version": 2,
	"styles": {
		"blocks": {
			"core/paragraph": {
				"typography": {
					"fontFamily": "Georgia, serif",
					"fontSize": "1.25rem",
					"fontStyle": "normal",
					"fontWeight": "500",
					"letterSpacing": "0",
					"lineHeight": "1.6",
					"textDecoration": "none"
				}
			}
		}
	}
}
CSS
The 
css property lets you write custom CSS directly in 
theme.json for a block or element:
Property
Type
CSS Property
css
string
—
Example usage in 
theme.json:
{
	"version": 2,
	"styles": {
		"blocks": {
			"core/gallery": {
				"css": "--wp--style--gallery-gap-default: 1rem;"
			}
		}
	}
}
For an in-depth look at how to use the 
css style property, read Per-block CSS with 
theme.json on the WordPress Developer Blog.

Using Presets
In the 
theme.json Settings documentation, you learned how to register custom presets, such as a color palette, font sizes, a spacing scale, and more. In the Styles documentation, you’ve learned how to apply CSS styles via 
theme.json.
Now it’s time to combine these two concepts by applying styles using the presets that you’ve registered.
In the styles documentation, you will often see examples using hard-coded CSS values. This is primarily for the sake of demonstration. You will almost always use registered presets instead. This makes it much easier to manage everything from a single location.
What are presets?
Essentially, presets are options that you register—generally for users to select from the UI—that map to CSS custom properties.
For example, when you learned how to register custom font sizes, you added your presets to 
settings.typography.fontSizes. WordPress takes each of those font sizes and creates a CSS custom property with the name of 
--wp--preset--font-size–{$slug}.
WordPress itself, your theme, plugins, and even users can register presets for the various features that are supported. And WordPress creates CSS custom properties for all registered presets with the name of 
--wp--preset–{$feature}-{$slug}.
Let’s look at a basic example of a custom color palette with three colors:
{
	"version": 2,
	"settings": {
		"color": {
			"palette": [
				{
					"color": "#ffffff",
					"name": "Base",
					"slug": "base"
				},
				{
					"color": "#000000",
					"name": "Contrast",
					"slug": "contrast"
				},
				{
					"color": "#89cff0",
					"name": "Primary",
					"slug": "primary"
				}
			]
		}
	}
}
This creates three CSS custom properties, which WordPress will output in the editor and on the front end:
body {
	--wp--preset--color--base: #ffffff;
	--wp--preset--color--contrast: #000000;
	--wp--preset--color--primary: #89cff0;
}
At the end of the day, presets are merely a standardized method of creating options in the interface and generating CSS custom properties.
Applying presets as styles
Because presets are registered as settings, they are available to select in the user interface. But you must apply them as styles if you want to use them as part of your theme’s default design.
Let’s build off the custom color palette from the previous section. Suppose you wanted to apply these styles using your registered presets:
The site’s background color should use the 
base preset.
The site’s primary text color should use the 
contrast preset.
Link colors should use the 
primary preset.
To reference presets in 
theme.json, there is a special syntax that you can use: 
var:preset|$feature|$slug. So 
base color in this instance would be 
var:preset|color|base.
With that plan in mind and using what you’ve already learned from this chapter, try your hand at recreating this in 
theme.json. Your code should look like this:
{
	"version": 2,
	"settings": {
		"color": {
			"palette": [
				{
					"color": "#ffffff",
					"name": "Base",
					"slug": "base"
				},
				{
					"color": "#000000",
					"name": "Contrast",
					"slug": "contrast"
				},
				{
					"color": "#89cff0",
					"name": "Primary",
					"slug": "primary"
				}
			]
		}
	},
	"styles": {
		"color": {
			"text": "var:preset|color|contrast",
			"background": "var:preset|color|base"
		},
		"elements": {
			"link": {
				"color": {
					"text": "var:preset|color|primary"
				}
			}
		}
	}
}
If you test your site on the front end or via the editor, you should see that your colors have correctly applied:
The next step now is to figure out which elements and blocks you want to apply other presets to. Depending on the complexity of your theme, this can be as simple as a few custom colors to hundreds of lines of JSON code. Really, what you do from here is entirely up to you.
Technically, you can reference presets using the CSS syntax of 
var( --wp--preset--{$feature}--{$slug} ). But the WordPress 
var:preset|$feature|$slug syntax works much better and always appears correctly throughout the interface in the WordPress admin. Save the CSS syntax for when you are actually writing CSS.
Referencing custom presets
In the Custom Settings documentation, you learned how to create “custom” presets. These are non-standard CSS custom properties that you can register, and WordPress generates the CSS output for you.
These use a different naming convention in comparison to standard presets. Essentially, whenever you used the term 
preset in your code for standard presets, you would exchange that for 
custom when dealing with custom presets.
Let’s walk through an example. Assume that you wanted to register some CSS custom properties for handling line heights in your theme design. You would add this to your 
theme.json file:
{
	"version": 2,
	"settings": {
		"custom": {
			"lineHeight": {
				"xs": "1",
				"sm": "1.25",
				"md": "1.5",
				"lg": "1.75"
			}
		}
	}
}
WordPress will generate these custom line heights as CSS custom properties in the editor and on the front end:
body {
	--wp--custom--line-height--xs: 1;
	--wp--custom--line-height--sm: 1.25;
	--wp--custom--line-height--md: 1.5;
	--wp--custom--line-height--lg: 1.75;
}
To reference these as styles in 
theme.json, you would use the 
var:custom syntax instead of 
var:preset.
Suppose you wanted to apply the registered 
md line-height size as the default line height at the root/global level. For that, you would need to target 
styles.typography.lineHeight.
Here is what the full code would look like in 
theme.json:
{
	"version": 2,
	"settings": {
		"custom": {
			"lineHeight": {
				"xs": "1",
				"sm": "1.25",
				"md": "1.5",
				"lg": "1.75"
			}
		}
	},
	"styles": {
		"typography": {
			"lineHeight": "var:custom|line-height|md"
		}
	}
}
Of course, you could use your other custom line-height presets for styling other elements and blocks.
Available presets
WordPress has several features that you can register presets for. You can find these presets in their corresponding settings docs (the specific properties are noted in parentheses):
Color (
palette)
Shadow (
presets)
Spacing (
spacingScale, 
spacingSizes)
Typography (
fontSizes, 
fontFamily)
Custom

Block Type Patterns
One of the most useful capabilities of patterns is the ability to tie them directly to one or more block types. For example, you can assign a gallery pattern to the Gallery (
core/gallery) block type and use that specific pattern whenever you insert a new Gallery.
But the feature offers even more than that. In this article, you will learn how to add a basic connection between a block type and a pattern and how to take advantage of some special cases in WordPress.
Besides the techniques described below, block type patterns are also needed for creating starter page patterns, which you can learn more about in the Starter Patterns documentation.
Block-specific patterns
It’s important to note that patterns that are connected to a block type behave just like other patterns. What you’re doing is making WordPress aware that the pattern is meant for one or more block types.
For many cases, you may simply want to create a pattern that serves as a starting point when inserting a specific block, and that’s where block type patterns are often useful.
Register a block type pattern
As described in Registering Patterns, you must assign a value to the 
Block Types header field in your pattern file. This field can accept one or more comma-separated block types, which must include the block’s namespace and slug (e.g., 
namespace/slug).
Here is what the file header of pattern tied to the Cover block might look like:
<?php
/**
 * Title: Cover With Contrast Background
 * Slug: themeslug/cover-contrast
 * Categories: banner
 * Block Types: core/cover
 * Viewport Width: 1376
 */
?>
Build a block type pattern
Let’s take what you’ve learned so far and create a pattern for a specific block. In this example, you will create a simple Cover block with a single nested Heading and a background with the 
contrast color preset.
Create a new file named 
cover-contrast.php in your theme’s 
/patterns folder and paste this code inside it:
<?php
/**
 * Title: Cover With Contrast Background
 * Slug: themeslug/cover-contrast
 * Categories: banner
 * Block Types: core/cover
 * Viewport Width: 1376
 */
?>
<!-- wp:cover {"overlayColor":"contrast","isUserOverlayColor":true,"align":"full","style":{"elements":{"link":{"color":{"text":"var:preset|color|base"}}}},"textColor":"base","layout":{"type":"constrained"}} -->
<div class="wp-block-cover alignfull has-base-color has-text-color has-link-color">
	<span aria-hidden="true" class="wp-block-cover__background has-contrast-background-color has-background-dim-100 has-background-dim"></span>
	<div class="wp-block-cover__inner-container">
		<!-- wp:heading {"textAlign":"center"} -->
			<h2 class="wp-block-heading has-text-align-center"><?php esc_html_e( 'A simple heading', 'themeslug' ); ?></h2>
		<!-- /wp:heading -->
	</div>
</div>
<!-- /wp:cover -->
Once you’ve saved your pattern file, it should appear as normal in the inserter and Pattern Library. But the most important thing is to check that it’s working as a block type pattern.
Open a new post or page in your WordPress admin and insert a Cover block but don’t make any change to it. Then, click the Cover block’s icon in the toolbar. You should see a Patterns menu item, and if you click that, your new pattern will appear:
From there, if you select the pattern that you’ve registered, it will transform your inserted Cover block inside the content area:
And that is the basics of how block type patterns work. But WordPress has some special handling for some blocks, which you will learn about below.
Query Loop patterns
The Query Loop block is one of the most unique and useful blocks to create custom patterns for. It gives you and your theme users the ability to quickly insert or replace existing Query blocks with an alternative posts layout.
The technique is the same as other block type patterns. You must add the 
core/query block type to the pattern’s 
Block Types file header field.
Let’s create a basic two-column grid that shows each post’s featured image, title, excerpt and date. You can, of course, use whatever layout and design that you want.
For now, create a new 
query-two-columns.php file in your theme’s 
/patterns folder and paste this code into it:
<?php
/**
 * Title: Query: Two Columns
 * Slug: themeslug/query-two-columns
 * Categories: posts
 * Block Types: core/query
 * Viewport Width: 1376
 */
?>
<!-- wp:query {"query":{"perPage":6,"pages":0,"offset":0,"postType":"post","order":"desc","orderBy":"date","author":"","search":"","exclude":[],"sticky":"","inherit":false},"align":"wide"} -->
<div class="wp-block-query alignwide">
		<!-- wp:post-template {"style":{"spacing":{"blockGap":"var:preset|spacing|40"}},"layout":{"type":"grid","columnCount":2}} -->
		<!-- wp:post-featured-image {"isLink":true,"aspectRatio":"4/3","align":"wide"} /-->
		<!-- wp:post-title {"isLink":true,"fontSize":"large"} /-->
		<!-- wp:post-excerpt {"showMoreOnNewLine":false,"excerptLength":26} /-->
		<!-- wp:post-date /-->
	<!-- /wp:post-template -->
</div>
<!-- /wp:query -->
There are two ways to take advantage of Query Loop patterns, like the one you just created. The first is to insert a new Query Loop block into a page or template:
You should see a couple of buttons for adding a Query Loop from that point. Click the Choose button.
This will bring up the Choose a pattern modal. In this modal, your pattern will appear and can be selected:
Once selected, your pattern will be inserted into the canvas of the page or template that you are editing:
The second method of using Query Loop patterns is much the same. You can replace an existing pattern (even the one you just inserted) by clicking the Replace button in the toolbar. It will bring up the same Choose a pattern modal, and the process of choosing a pattern is the same.
Template Part patterns
Because template parts are technically blocks themselves, you can also use them as a pattern’s block types. There is one limitation: only parts that use the Header and Footer template part areas are supported. But these are the most common types anyway.
When targeting a specific template part, its block type name will have a third component: the template part area. So if you want to target the Header part, you will pass a block type of 
core/template-part/header. And for the Footer part, use 
core/template-part/footer.
Let’s create a basic Header template part with a centered logo, title, and nav menu. You will use this to replace the existing header on your site.
Create a new file named 
header-centered.php in your theme’s 
/patterns folder. Then copy and paste this code into it:
<?php
/**
 * Title: Header: Centered
 * Slug: themeslug/header-centered
 * Categories: header
 * Block Types: core/template-part/header
 * Viewport Width: 1376
 */
?>
<!-- wp:group {"align":"wide","layout":{"type":"flex","orientation":"vertical","justifyContent":"center"}} -->
<div class="wp-block-group alignwide">
	<!-- wp:site-logo {"width":60} /-->
	<!-- wp:site-title {"level":0} /-->
	<!-- wp:navigation {"layout":{"type":"flex","justifyContent":"right","orientation":"horizontal"},"style":{"spacing":{"margin":{"top":"0"},"blockGap":"var:preset|spacing|20"},"layout":{"selfStretch":"fit","flexSize":null}}} /-->
</div>
<!-- /wp:group -->
Once you save this file, go to Appearance > Editor in your WordPress admin and select the on the Header block.
Now click the Options button (⋮ icon) in the toolbar. You should see a Replace option in the dropdown:
Once you click the Replace dropdown menu item, a new modal titled Choose a header will appear, and you should see your Header: Centered pattern in the available patterns grid:
By selecting this pattern or another, you can replace the entire Header template part. This process works the same for Footer template parts.
Parts for custom template part areas cannot yet take advantage of this feature. There is an open ticket that has not been patched to handle areas other than Header and Footer.

Introduction to Patterns
Block patterns (“patterns,” for short) are one of the most powerful features at a theme author’s disposal. Introduced in WordPress 5.4, patterns made it easier for users to insert more complex layouts from the block editor while opening a world of possibilities to designers.
This article provides an overarching definition of what patterns are and how they work. This will serve as a foundation as you read through the other articles in this chapter.
What are patterns?
Essentially, a pattern is nothing more than one or more blocks that have been pre-configured and presented to the end-user. Think of them as reusable groups of blocks.
And that’s it. Really. Patterns are just groups of blocks.
They are ideal as starting points for users to insert into their post and page content, but they are also useful when used inside of templates.
Users can insert them directly into a template from the Site Editor or into their content from the Post Editor:
In comparison to template parts, which is a similar feature for reusable groups of blocks, patterns also give you access to PHP when you bundle them inside a theme. This means that you can internationalize text within them, dynamically add URLs to include images, and more. And you will learn more about these things throughout this chapter.
Note that users can create and manage custom patterns from the Appearance > Editor > Patterns screen in the admin. You can also use this screen to manage your own patterns in your development install:
If you are building a classic theme, this screen is unavailable. But, as of WordPress 6.5, you can access patterns through the Appearance > Patterns screen instead.
Types of patterns
Essentially, there are two types of patterns:
Synced: Patterns that remain unchanged regardless of how many times or where it’s used on the website. These were formerly called “reusable blocks” in older versions of WordPress. Note: these can only be created and managed from the WordPress admin.
Not synced: Patterns that, when inserted via the Block Editor, create a new instance of the pattern’s blocks. Any changes made to the inserted blocks do not affect other uses of the pattern. Changes to the pattern in the future also do not affect prior uses of it.
By the nature of how the pattern system works, all patterns registered by the theme are of the Not synced type. There is an open ticket for syncing theme-registered patterns, but it is not currently possible.
Managing patterns in the WordPress admin
Even when building a theme, you will often build patterns directly from the admin before bundling and registering them from within the theme itself. This can also be a good way to store and manage your patterns locally until you are satisfied that they are ready to include in your theme.
It’s also good practice to get a feel for how users interact with patterns.
You can manage patterns by visiting the Appearance > Editor screen in your WordPress admin and clicking on the Patterns item in the sidebar.
Creating custom patterns
On the Patterns screen, you must click on the Create pattern button (+ icon), which will give you a choice to create several options:
Create pattern
Create template part
Import pattern from JSON
Select the Create pattern option, which will trigger an overlay modal that looks like this:
You’ll need to fill out three fields:
Name: Decide on a name for the pattern you are creating.
Categories: Add one or more categories that your pattern will fit into.
Synced: Decide on whether your pattern should be synced. If you plan to ship this with your theme, you should toggle this option off just so that it behaves the same as it would coming from a theme.
Once you click the Create button, it will take you to the Pattern Editor. From there, it works just like any other Editor in WordPress. Add the blocks that you want to in your pattern and adjust their settings and styles to suit your needs.
Here is an example of a basic “Welcome Hero” pattern:
Just be sure to hit the Save button. From there, you can use your pattern just like you’d use any other pattern on your site.
You can also view and edit any custom patterns you’ve created via the Patterns > My Patterns section in the sidebar:
The My Patterns section is always where any user-created patterns will appear in the WordPress admin. They will also appear under the All patterns section and any other categories they were assigned to.
Copying a pattern to your theme
The Editor interface is a nice and easy method for creating patterns. But this is the Theme Handbook, so you’re probably wanting to know how to bundle this pattern that you’ve created with your theme.
For that, you need to copy the pattern code itself. You’ll learn what to do with pattern code in the Registering Patterns article in this chapter.
There are a few different methods for copying pattern code. But the easiest way is to click the Options button (⋮ icon) at the top of the editor and select the Copy all blocks option in the dropdown menu:
For the particular pattern shown in the screenshot, it will give you this block markup:
<!-- wp:cover {"overlayColor":"contrast","align":"full"} -->
<div class="wp-block-cover alignfull"><span aria-hidden="true" class="wp-block-cover__background has-contrast-background-color has-background-dim-100 has-background-dim"></span><div class="wp-block-cover__inner-container"><!-- wp:group {"style":{"spacing":{"blockGap":"2.5rem"}},"layout":{"type":"constrained","wideSize":"%","contentSize":"75%"}} -->
<div class="wp-block-group"><!-- wp:heading {"textAlign":"center"} -->
<h2 class="wp-block-heading has-text-align-center">Welcome to My Site</h2>
<!-- /wp:heading -->
<!-- wp:paragraph {"align":"center"} -->
<p class="has-text-align-center">This is my little home away from home. Here, you will get to know me. I'll share my likes, hobbies, and more. Every now and then, I'll even have something interesting to say in a blog post.</p>
<!-- /wp:paragraph -->
<!-- wp:buttons {"layout":{"type":"flex","justifyContent":"center"}} -->
<div class="wp-block-buttons"><!-- wp:button {"className":"is-style-outline"} -->
<div class="wp-block-button is-style-outline"><a class="wp-block-button__link wp-element-button">See My Popular Posts →︎</a></div>
<!-- /wp:button --></div>
<!-- /wp:buttons --></div>
<!-- /wp:group --></div></div>
<!-- /wp:cover -->
In the Registering Patterns documentation, you will learn how to take that block markup and bundle it as a pattern with your theme.
Managing theme-bundled patterns
There is currently no standard for theme authors to manage their patterns or port them directly to their theme without going through the process outlined above.
For the moment, it’s entirely up to you to decide how you want to integrate pattern management into your workflow. Some things to consider:
You’ll need to manually copy and paste a pattern’s block markup from the admin UI to your theme.
If you need to make changes to a pattern’s block markup, there’s no way to keep the pattern in your theme and the version you built in the admin in sync.
These are certainly challenges that you’ll encounter when deciding the best method to use. There is an open discussion for the official Create Block Theme plugin that would explore pattern management, and that is the best place to discuss with other theme authors the best path forward.

Patterns and Block Locking
The Block Locking API is a powerful set of features that lets you lock the behavior of blocks and how users interact with them. You can control whether users can remove, move, or customize blocks, which lets you further curate the editing experience of your themes.
This article will explore some of the ways that you can utilize the API within your theme’s patterns. But for a deeper dive into the API, please refer to the Block Locking documentation in the Block Editor Handbook.
You are not only limited to using Block Locking in patterns. You can also apply the methods in this article to templates.
What is Block Locking?
The Block Locking API lets you control how a user interacts with blocks on their site. The types of locking you can do are:
Disabling block movement in the editor.
Preventing a block from being removed.
Preventing new blocks from being inserted.
Disabling editing block settings other than content and media.
This can be really useful depending on the scenario. For example, it often makes sense to lock a site header pattern, which can be complex, by disabling the deletion of its inner blocks by accident.
There are also two types of locking the API offers: block and template. Locking at the block level means preventing the user from taking some actions for the individual block. Locking at the template level means preventing the user from some actions at a “group” level.
It’s important to note that “template” here refers to a section of blocks nested within a container block, such as Group, Cover, etc. It’s not referring specifically to template files.
Block locking
In this section, you will learn how to lock individual blocks. Namely, preventing a user from moving a block or removing it altogether.
First, you should familiarize yourself with how to lock blocks from the UI. Let’s start by creating a custom “event” pattern to work for throughout the remainder of this article.
Create a new file in your theme named 
/patterns/event.php and place the following code into it:
<?php
/**
 * Title: Event
 * Slug: themeslug/event
 * Categories: banner
 * Viewport Width: 1376
 */
?>
<!-- wp:group {"align":"wide","style":{"elements":{"link":{"color":{"text":"var:preset|color|base-2"}}},"spacing":{"padding":{"top":"var:preset|spacing|30","bottom":"var:preset|spacing|30","left":"var:preset|spacing|30","right":"var:preset|spacing|30"}}},"backgroundColor":"contrast","textColor":"base-2","layout":{"type":"default"}} -->
<div class="wp-block-group alignwide has-base-2-color has-contrast-background-color has-text-color has-background has-link-color" style="padding-top:var(--wp--preset--spacing--30);padding-right:var(--wp--preset--spacing--30);padding-bottom:var(--wp--preset--spacing--30);padding-left:var(--wp--preset--spacing--30)">
	<!-- wp:image {"sizeSlug":"full","linkDestination":"none"} -->
	<figure class="wp-block-image size-full"><img src="https://s.w.org/patterns/files/2021/06/Group-17-scaled.jpg" alt="Image of a woman being carried through the air by swans."/></figure>
	<!-- /wp:image -->
	<!-- wp:columns {"verticalAlignment":"center"} -->
	<div class="wp-block-columns are-vertically-aligned-center">
		
		<!-- wp:column {"verticalAlignment":"center"} -->
		<div class="wp-block-column is-vertically-aligned-center">
			<!-- wp:paragraph -->
			<p><strong><?php esc_html_e( 'Location:', 'themeslug' ); ?></strong><br><?php esc_html_e( '82 Main St. Brooklyn, NY', 'themeslug' ); ?></p>
			<!-- /wp:paragraph -->
		</div>
		<!-- /wp:column -->
		<!-- wp:column {"verticalAlignment":"center"} -->
		<div class="wp-block-column is-vertically-aligned-center">
			<!-- wp:paragraph -->
			<p><strong><?php esc_html_e( 'Date:', 'themeslug' ); ?></strong><br><?php esc_html_e( 'October 24, 2021', 'themeslug' ); ?></p>
			<!-- /wp:paragraph -->
		</div>
		<!-- /wp:column -->
		<!-- wp:column {"verticalAlignment":"center"} -->
		<div class="wp-block-column is-vertically-aligned-center">
			<!-- wp:buttons -->
			<div class="wp-block-buttons">
				<!-- wp:button {"width":100,"className":"is-style-outline"} -->
				<div class="wp-block-button has-custom-width wp-block-button__width-100 is-style-outline"><a class="wp-block-button__link wp-element-button"><?php esc_html_e( 'Purchase Tickets' ); ?></a></div>
				<!-- /wp:button -->
			</div>
			<!-- /wp:buttons -->
		</div>
		<!-- /wp:column -->
	</div>
	<!-- /wp:columns -->
</div>
<!-- /wp:group -->
Then go to the post editor and insert your new pattern. Once you’ve done that, you should see the pattern in the content area.
Now select the Image block (or any block) in the pattern. Then click the Options button in the block toolbar. You should see a Lock option:
This will bring up a modal for various locking options, which you’ll learn about in the following sections.
This type of locking is shown in the UI, and a theme user will be able to override it from the UI. For publicly-distributed themes, this is a good thing. But for client work, this type of access may be undesirable. If you need to control permissions to the locking UI, see the instructions in the Locking API docs: Change permissions to control locking ability.
Disable block movement
One of the primary use cases of the Block Locking API is to prevent users from accidentally moving blocks around within a pattern, altering the layout. In the Lock modal, you will see an option to Disable movement. Try selecting this option for the Image block from the event pattern:
Under the hood, when you select this option, WordPress will add a new 
lock attribute to the block markup that looks like this:
<!-- wp:image {"lock":{"move":true,"remove":false}} -->
Because you’ve selected the Disable movement option, the 
move key will have a value of 
true (i.e., movement has been locked).
Now try creating a new version of your pattern with the Image block’s movement disabled. Add a new 
/patterns/event-disable-movement.php file to your theme and paste this code in:
<?php
/**
 * Title: Event (Disable Movement)
 * Slug: themeslug/event-disable-movement
 * Categories: banner
 * Viewport Width: 1376
 */
?>
<!-- wp:group {"align":"wide","style":{"elements":{"link":{"color":{"text":"var:preset|color|base-2"}}},"spacing":{"padding":{"top":"var:preset|spacing|30","bottom":"var:preset|spacing|30","left":"var:preset|spacing|30","right":"var:preset|spacing|30"}}},"backgroundColor":"contrast","textColor":"base-2","layout":{"type":"default"}} -->
<div class="wp-block-group alignwide has-base-2-color has-contrast-background-color has-text-color has-background has-link-color" style="padding-top:var(--wp--preset--spacing--30);padding-right:var(--wp--preset--spacing--30);padding-bottom:var(--wp--preset--spacing--30);padding-left:var(--wp--preset--spacing--30)">
	<!-- wp:image {"sizeSlug":"full","linkDestination":"none","lock":{"move":true,"remove":false}} -->
	<figure class="wp-block-image size-full"><img src="https://s.w.org/patterns/files/2021/06/Group-17-scaled.jpg" alt="Image of a woman being carried through the air by swans."/></figure>
	<!-- /wp:image -->
	<!-- wp:columns {"verticalAlignment":"center"} -->
	<div class="wp-block-columns are-vertically-aligned-center">
		
		<!-- wp:column {"verticalAlignment":"center"} -->
		<div class="wp-block-column is-vertically-aligned-center">
			<!-- wp:paragraph -->
			<p><strong><?php esc_html_e( 'Location:', 'themeslug' ); ?></strong><br><?php esc_html_e( '82 Main St. Brooklyn, NY', 'themeslug' ); ?></p>
			<!-- /wp:paragraph -->
		</div>
		<!-- /wp:column -->
		<!-- wp:column {"verticalAlignment":"center"} -->
		<div class="wp-block-column is-vertically-aligned-center">
			<!-- wp:paragraph -->
			<p><strong><?php esc_html_e( 'Date:', 'themeslug' ); ?></strong><br><?php esc_html_e( 'October 24, 2021', 'themeslug' ); ?></p>
			<!-- /wp:paragraph -->
		</div>
		<!-- /wp:column -->
		<!-- wp:column {"verticalAlignment":"center"} -->
		<div class="wp-block-column is-vertically-aligned-center">
			<!-- wp:buttons -->
			<div class="wp-block-buttons">
				<!-- wp:button {"width":100,"className":"is-style-outline"} -->
				<div class="wp-block-button has-custom-width wp-block-button__width-100 is-style-outline"><a class="wp-block-button__link wp-element-button"><?php esc_html_e( 'Purchase Tickets' ); ?></a></div>
				<!-- /wp:button -->
			</div>
			<!-- /wp:buttons -->
		</div>
		<!-- /wp:column -->
	</div>
	<!-- /wp:columns -->
</div>
<!-- /wp:group -->
Now, anytime a user adds this pattern to their content, they won’t be able to move the Image block within the pattern.
Just because the Image block’s movement has been disabled, it doesn’t affect other blocks within the pattern. For example, it’s still possible to move the Columns block. You would need to disable both blocks from being moved to stop the user from moving either.
Prevent block removal
For some patterns, you will want to keep a block from being deleted altogether. For example, in the event pattern, the Image block may be integral to the pattern’s design.
Starting from the original event pattern, repeat the process of opening the Lock modal. This time, select the Prevent removal option:
Again, WordPress will automatically insert the 
lock attribute in the block markup, which will look like this:
<!-- wp:image {"lock":{"move":false,"remove":true}} -->
This time, the 
remove option is set to 
true (i.e., removal has been locked).
Now create an alternate version of your pattern with the Image block’s removal disabled. Add a new 
/patterns/event-prevent-removal.php file to your theme and paste this code in:
<?php
/**
 * Title: Event (Prevent Removal)
 * Slug: themeslug/event-prevent-removal
 * Categories: banner
 * Viewport Width: 1376
 */
?>
<!-- wp:group {"align":"wide","style":{"elements":{"link":{"color":{"text":"var:preset|color|base-2"}}},"spacing":{"padding":{"top":"var:preset|spacing|30","bottom":"var:preset|spacing|30","left":"var:preset|spacing|30","right":"var:preset|spacing|30"}}},"backgroundColor":"contrast","textColor":"base-2","layout":{"type":"default"}} -->
<div class="wp-block-group alignwide has-base-2-color has-contrast-background-color has-text-color has-background has-link-color" style="padding-top:var(--wp--preset--spacing--30);padding-right:var(--wp--preset--spacing--30);padding-bottom:var(--wp--preset--spacing--30);padding-left:var(--wp--preset--spacing--30)">
	<!-- wp:image {"sizeSlug":"full","linkDestination":"none","lock":{"move":false,"remove":true}} -->
	<figure class="wp-block-image size-full"><img src="https://s.w.org/patterns/files/2021/06/Group-17-scaled.jpg" alt="Image of a woman being carried through the air by swans."/></figure>
	<!-- /wp:image -->
	<!-- wp:columns {"verticalAlignment":"center"} -->
	<div class="wp-block-columns are-vertically-aligned-center">
		
		<!-- wp:column {"verticalAlignment":"center"} -->
		<div class="wp-block-column is-vertically-aligned-center">
			<!-- wp:paragraph -->
			<p><strong><?php esc_html_e( 'Location:', 'themeslug' ); ?></strong><br><?php esc_html_e( '82 Main St. Brooklyn, NY', 'themeslug' ); ?></p>
			<!-- /wp:paragraph -->
		</div>
		<!-- /wp:column -->
		<!-- wp:column {"verticalAlignment":"center"} -->
		<div class="wp-block-column is-vertically-aligned-center">
			<!-- wp:paragraph -->
			<p><strong><?php esc_html_e( 'Date:', 'themeslug' ); ?></strong><br><?php esc_html_e( 'October 24, 2021', 'themeslug' ); ?></p>
			<!-- /wp:paragraph -->
		</div>
		<!-- /wp:column -->
		<!-- wp:column {"verticalAlignment":"center"} -->
		<div class="wp-block-column is-vertically-aligned-center">
			<!-- wp:buttons -->
			<div class="wp-block-buttons">
				<!-- wp:button {"width":100,"className":"is-style-outline"} -->
				<div class="wp-block-button has-custom-width wp-block-button__width-100 is-style-outline"><a class="wp-block-button__link wp-element-button"><?php esc_html_e( 'Purchase Tickets' ); ?></a></div>
				<!-- /wp:button -->
			</div>
			<!-- /wp:buttons -->
		</div>
		<!-- /wp:column -->
	</div>
	<!-- /wp:columns -->
</div>
<!-- /wp:group -->
Now, whenever a user inserts this pattern, they will not be able to remove the Image block. They’ll still be able to edit the image itself and any settings, though.
You can combine both of these techniques, locking movement and removal, depending on your use case. For some patterns, this is often needed to keep the design of the pattern intact.
Template locking
Template locking refers to locking all of the nested blocks within a container-type block. There are three types of locking that you can accomplish with template locking:
all: Combined with the block locking methods covered earlier, lock all blocks within the container.
insert: Prevent users from inserting new blocks within the container.
contentOnly: Lock down all block settings within the container, only allowing the user to edit content (e.g., text and media).
Template locking is only possible for a subset of container-type blocks in Core:
Group
Cover
Columns
Column
Navigation
Locking all nested blocks
With the built-in UI controls, you can lock all nested blocks within a pattern if it’s wrapped in one of the supported container-type blocks.
This type of locking builds off the block locking covered earlier in this article. You can choose to disable movement, prevent removal, or both for all nested blocks.
When clicking on the wrapping Group block inside your event pattern and opening the Lock modal, select both the Disable movement and Prevent removal options. You should also see another option labeled Apply to all blocks, which will let you apply these rules to every block inside the Group:
If you look at the underlying block markup, you will see a new 
templateLock attribute, which will be set to 
all. You will also see the 
lock attribute with both 
move and 
remove set to 
true:
<!-- wp:group {"templateLock":"all","lock":{"move":true,"remove":true}} -->
Like with individual block locking, you can mix and match what you want to lock at the template level.
Now create a new file named 
/patterns/event-lock-all.php in your theme and paste the following code into it:
<?php
/**
 * Title: Event (Lock All)
 * Slug: themeslug/event-lock-all
 * Categories: banner
 * Viewport Width: 1376
 */
?>
<!-- wp:group {"templateLock":"all","lock":{"move":true,"remove":true},"align":"wide","style":{"elements":{"link":{"color":{"text":"var:preset|color|base-2"}}},"spacing":{"padding":{"top":"var:preset|spacing|30","bottom":"var:preset|spacing|30","left":"var:preset|spacing|30","right":"var:preset|spacing|30"}}},"backgroundColor":"contrast","textColor":"base-2","layout":{"type":"default"}} -->
<div class="wp-block-group alignwide has-base-2-color has-contrast-background-color has-text-color has-background has-link-color" style="padding-top:var(--wp--preset--spacing--30);padding-right:var(--wp--preset--spacing--30);padding-bottom:var(--wp--preset--spacing--30);padding-left:var(--wp--preset--spacing--30)">
	<!-- wp:image {"sizeSlug":"full","linkDestination":"none"} -->
	<figure class="wp-block-image size-full"><img src="https://s.w.org/patterns/files/2021/06/Group-17-scaled.jpg" alt="Image of a woman being carried through the air by swans."/></figure>
	<!-- /wp:image -->
	<!-- wp:columns {"verticalAlignment":"center"} -->
	<div class="wp-block-columns are-vertically-aligned-center">
		
		<!-- wp:column {"verticalAlignment":"center"} -->
		<div class="wp-block-column is-vertically-aligned-center">
			<!-- wp:paragraph -->
			<p><strong><?php esc_html_e( 'Location:', 'themeslug' ); ?></strong><br><?php esc_html_e( '82 Main St. Brooklyn, NY', 'themeslug' ); ?></p>
			<!-- /wp:paragraph -->
		</div>
		<!-- /wp:column -->
		<!-- wp:column {"verticalAlignment":"center"} -->
		<div class="wp-block-column is-vertically-aligned-center">
			<!-- wp:paragraph -->
			<p><strong><?php esc_html_e( 'Date:', 'themeslug' ); ?></strong><br><?php esc_html_e( 'October 24, 2021', 'themeslug' ); ?></p>
			<!-- /wp:paragraph -->
		</div>
		<!-- /wp:column -->
		<!-- wp:column {"verticalAlignment":"center"} -->
		<div class="wp-block-column is-vertically-aligned-center">
			<!-- wp:buttons -->
			<div class="wp-block-buttons">
				<!-- wp:button {"width":100,"className":"is-style-outline"} -->
				<div class="wp-block-button has-custom-width wp-block-button__width-100 is-style-outline"><a class="wp-block-button__link wp-element-button"><?php esc_html_e( 'Purchase Tickets' ); ?></a></div>
				<!-- /wp:button -->
			</div>
			<!-- /wp:buttons -->
		</div>
		<!-- /wp:column -->
	</div>
	<!-- /wp:columns -->
</div>
<!-- /wp:group -->
Whenever a user inserts this new pattern into their content, they will not be able to move or remove any of the blocks within the pattern. But they can still edit each block’s content and settings.
Preventing new blocks from being inserted
You can also lock your container-type blocks in patterns from having new blocks inserted into them. This is useful when you need to keep tight control over what is allowed within the design.
Unlock previous methods of locking blocks, this method has no UI controls associated with it. This means that you must edit the block markup directly by adding the 
templateLock value.
Take a look at what this looks like when applied to a wrapping Group block:
<!-- wp:group {"templateLock":"insert"} -->
As you can see, the 
templateLock attribute is set to 
insert (i.e, the Group has locked inserting new blocks).
Now create a new file in your theme named 
/patterns/event-prevent-insert.php and paste the following code into it:
<?php
/**
 * Title: Event (Prevent Insert)
 * Slug: themeslug/event-prevent-insert
 * Categories: banner
 * Viewport Width: 1376
 */
?>
<!-- wp:group {"templateLock":"insert","align":"wide","style":{"elements":{"link":{"color":{"text":"var:preset|color|base-2"}}},"spacing":{"padding":{"top":"var:preset|spacing|30","bottom":"var:preset|spacing|30","left":"var:preset|spacing|30","right":"var:preset|spacing|30"}}},"backgroundColor":"contrast","textColor":"base-2","layout":{"type":"default"}} -->
<div class="wp-block-group alignwide has-base-2-color has-contrast-background-color has-text-color has-background has-link-color" style="padding-top:var(--wp--preset--spacing--30);padding-right:var(--wp--preset--spacing--30);padding-bottom:var(--wp--preset--spacing--30);padding-left:var(--wp--preset--spacing--30)">
	<!-- wp:image {"sizeSlug":"full","linkDestination":"none"} -->
	<figure class="wp-block-image size-full"><img src="https://s.w.org/patterns/files/2021/06/Group-17-scaled.jpg" alt="Image of a woman being carried through the air by swans."/></figure>
	<!-- /wp:image -->
	<!-- wp:columns {"verticalAlignment":"center"} -->
	<div class="wp-block-columns are-vertically-aligned-center">
		
		<!-- wp:column {"verticalAlignment":"center"} -->
		<div class="wp-block-column is-vertically-aligned-center">
			<!-- wp:paragraph -->
			<p><strong><?php esc_html_e( 'Location:', 'themeslug' ); ?></strong><br><?php esc_html_e( '82 Main St. Brooklyn, NY', 'themeslug' ); ?></p>
			<!-- /wp:paragraph -->
		</div>
		<!-- /wp:column -->
		<!-- wp:column {"verticalAlignment":"center"} -->
		<div class="wp-block-column is-vertically-aligned-center">
			<!-- wp:paragraph -->
			<p><strong><?php esc_html_e( 'Date:', 'themeslug' ); ?></strong><br><?php esc_html_e( 'October 24, 2021', 'themeslug' ); ?></p>
			<!-- /wp:paragraph -->
		</div>
		<!-- /wp:column -->
		<!-- wp:column {"verticalAlignment":"center"} -->
		<div class="wp-block-column is-vertically-aligned-center">
			<!-- wp:buttons -->
			<div class="wp-block-buttons">
				<!-- wp:button {"width":100,"className":"is-style-outline"} -->
				<div class="wp-block-button has-custom-width wp-block-button__width-100 is-style-outline"><a class="wp-block-button__link wp-element-button"><?php esc_html_e( 'Purchase Tickets' ); ?></a></div>
				<!-- /wp:button -->
			</div>
			<!-- /wp:buttons -->
		</div>
		<!-- /wp:column -->
	</div>
	<!-- /wp:columns -->
</div>
<!-- /wp:group -->
When a user adds this pattern into their post or page content, they will be able to customize the blocks within the pattern. But they will not be able to add any new blocks from within the UI.
Applying content-only editing
One of the most useful features for patterns is to use template locking to only allow the user to customize the content of a pattern. This can be useful when you need full control over the design but need to allow user input.
When this type of locking is applied to a container-type block, users will see a new Content panel when inspecting any block instead of the usual block settings:
This is also a type of locking that has no UI controls and must be manually applied to the block markup. If applied to the outer Group block of your pattern, it will look like this:
<!-- wp:group {"templateLock":"contentOnly"} -->
Note that the 
templateLock attribute is set to 
contentOnly, which means that everything but content editing is locked.
Now let’s apply this to the event pattern. Create a new file in your theme named 
/patterns/event-content-only.php and paste the following code into it:
<?php
/**
 * Title: Event (Content Only)
 * Slug: themeslug/event-content-only
 * Categories: banner
 * Viewport Width: 1376
 */
?>
<!-- wp:group {"templateLock":"contentOnly","align":"wide","style":{"elements":{"link":{"color":{"text":"var:preset|color|base-2"}}},"spacing":{"padding":{"top":"var:preset|spacing|30","bottom":"var:preset|spacing|30","left":"var:preset|spacing|30","right":"var:preset|spacing|30"}}},"backgroundColor":"contrast","textColor":"base-2","layout":{"type":"default"}} -->
<div class="wp-block-group alignwide has-base-2-color has-contrast-background-color has-text-color has-background has-link-color" style="padding-top:var(--wp--preset--spacing--30);padding-right:var(--wp--preset--spacing--30);padding-bottom:var(--wp--preset--spacing--30);padding-left:var(--wp--preset--spacing--30)">
	<!-- wp:image {"sizeSlug":"full","linkDestination":"none"} -->
	<figure class="wp-block-image size-full"><img src="https://s.w.org/patterns/files/2021/06/Group-17-scaled.jpg" alt="Image of a woman being carried through the air by swans."/></figure>
	<!-- /wp:image -->
	<!-- wp:columns {"verticalAlignment":"center"} -->
	<div class="wp-block-columns are-vertically-aligned-center">
		
		<!-- wp:column {"verticalAlignment":"center"} -->
		<div class="wp-block-column is-vertically-aligned-center">
			<!-- wp:paragraph -->
			<p><strong><?php esc_html_e( 'Location:', 'themeslug' ); ?></strong><br><?php esc_html_e( '82 Main St. Brooklyn, NY', 'themeslug' ); ?></p>
			<!-- /wp:paragraph -->
		</div>
		<!-- /wp:column -->
		<!-- wp:column {"verticalAlignment":"center"} -->
		<div class="wp-block-column is-vertically-aligned-center">
			<!-- wp:paragraph -->
			<p><strong><?php esc_html_e( 'Date:', 'themeslug' ); ?></strong><br><?php esc_html_e( 'October 24, 2021', 'themeslug' ); ?></p>
			<!-- /wp:paragraph -->
		</div>
		<!-- /wp:column -->
		<!-- wp:column {"verticalAlignment":"center"} -->
		<div class="wp-block-column is-vertically-aligned-center">
			<!-- wp:buttons -->
			<div class="wp-block-buttons">
				<!-- wp:button {"width":100,"className":"is-style-outline"} -->
				<div class="wp-block-button has-custom-width wp-block-button__width-100 is-style-outline"><a class="wp-block-button__link wp-element-button"><?php esc_html_e( 'Purchase Tickets' ); ?></a></div>
				<!-- /wp:button -->
			</div>
			<!-- /wp:buttons -->
		</div>
		<!-- /wp:column -->
	</div>
	<!-- /wp:columns -->
</div>
<!-- /wp:group -->
With this setting in place, the user will be able to edit the Image block’s media and the content of the individual Paragraph and Button blocks. But they won’t be able to make any design changes directly inside of the pattern.

Registering Patterns
In Introduction to Patterns, you learned how to create patterns from the WordPress admin interface. Now it’s time to learn how to add these custom patterns directly to your theme
This article will show you how to take a pattern’s block code and register it with WordPress from within your theme. It will also cover unregistering patterns and registering/unregistering pattern categories.
Creating patterns
If you’re unfamiliar with creating custom patterns, take a moment to study the Introduction to Patterns guide, which will walk you through the process.
Your pattern can be anything you like, but for the purposes of this article, the code shared below will be of a core Cover block with some blocks nested within it, following this structure:
Group
Heading
Paragraph
Buttons
Button
Feel free to try recreating this yourself from the editor, especially if you are just getting used to working with the editor. Here is a screenshot of the pattern from the editor:
You can also customize this however you like, but it’s recommended to keep this relatively simple for your first time creating a pattern.
Here is what the above pattern’s block markup looks like (read the Introduction to Patterns article for more information on getting pattern code):
<!-- wp:cover {"overlayColor":"contrast","align":"full"} -->
<div class="wp-block-cover alignfull"><span aria-hidden="true" class="wp-block-cover__background has-contrast-background-color has-background-dim-100 has-background-dim"></span><div class="wp-block-cover__inner-container"><!-- wp:group {"style":{"spacing":{"blockGap":"2.5rem"}},"layout":{"type":"constrained","wideSize":"%","contentSize":"75%"}} -->
<div class="wp-block-group"><!-- wp:heading {"textAlign":"center"} -->
<h2 class="wp-block-heading has-text-align-center">Welcome to My Site</h2>
<!-- /wp:heading -->
<!-- wp:paragraph {"align":"center"} -->
<p class="has-text-align-center">This is my little home away from home. Here, you will get to know me.  I'll share my likes, hobbies, and more.  Every now and then, I'll even have something interesting to say in a blog post.</p>
<!-- /wp:paragraph -->
<!-- wp:buttons {"layout":{"type":"flex","justifyContent":"center"}} -->
<div class="wp-block-buttons"><!-- wp:button {"className":"is-style-outline"} -->
<div class="wp-block-button is-style-outline"><a class="wp-block-button__link wp-element-button">See My Popular Posts →︎</a></div>
<!-- /wp:button --></div>
<!-- /wp:buttons --></div>
<!-- /wp:group --></div></div>
<!-- /wp:cover -->
For the remainder of this article, you will work with this same pattern, learning how to register it, unregister it, and customize it further.
It’s good practice to wrap most patterns in a Group, Cover, or other container block (i.e., a block that allows nested blocks). This makes it easier for your theme users to move the entire pattern around in the editor. You can also add a CSS class to this outer block for any custom styling that applies to the entire pattern.
Registering patterns
There are two methods for registering block patterns in WordPress:
By placing files with block markup in them into the /patterns folder in your theme.
By manually calling the 
register_block_pattern() function.
The most straightforward route is the first. You’ll learn how to do both in the next sections, but this handbook will recommend using the 
/patterns folder except in some edge cases.
Using the /patterns directory to register patterns
WordPress will recognize any pattern file placed in your theme’s 
/patterns folder, and it will automatically register it for you, provided that it has a valid pattern file header.
A file header is PHP-commented code with a list of key + value pairs at the top of a file. WordPress parses this information to gather metadata. In this case, the metadata is used to register a block pattern.
For pattern file headers, these are the keys that you can set:
Title: A human-readable title that can be translated.
Slug: A namespaced slug that is unique to your pattern in the form of 
namespace/pattern-name.
Categories: A comma-separated list of categories in which the pattern belongs.
Description: The long description of the registered pattern. Only shown to screen readers.
Viewport Width: The width of the 
<iframe> viewport when previewing the pattern (in pixels).
Inserter: Whether to show the pattern in the inserter. Defaults to 
true.
Keywords: A comma-separated list of keywords related to the pattern. Used when a user searches in the inserter.
Block Types: A comma-separated list of block types to associate the pattern with (e.g., 
core/cover, 
core/post-content).
Post Types: A comma-separated list of post types in which to limit the pattern (e.g., 
post, 
page). Defaults to all post types.
Template Types: A comma-separated list of template types the pattern fits with (e.g., 
home, 
single).
For most patterns, you should at least add the Title, Slug, and Categories fields. Pattern files should look like this:
<?php
/**
 * Title: Hero
 * Slug: themeslug/hero
 * Categories: featured
 */
?>
<!-- Pattern code goes here. -->
Now let’s add the code that you copied from the previous section into the 
/patterns/hero.php file in your theme:
<?php
/**
 * Title: Hero
 * Slug: themeslug/hero
 * Categories: featured
 */
?>
<!-- wp:cover {"overlayColor":"contrast","align":"full"} -->
<div class="wp-block-cover alignfull"><span aria-hidden="true" class="wp-block-cover__background has-contrast-background-color has-background-dim-100 has-background-dim"></span><div class="wp-block-cover__inner-container"><!-- wp:group {"style":{"spacing":{"blockGap":"2.5rem"}},"layout":{"type":"constrained","wideSize":"%","contentSize":"75%"}} -->
<div class="wp-block-group"><!-- wp:heading {"textAlign":"center"} -->
<h2 class="wp-block-heading has-text-align-center">Welcome to My Site</h2>
<!-- /wp:heading -->
<!-- wp:paragraph {"align":"center"} -->
<p class="has-text-align-center">This is my little home away from home. Here, you will get to know me. I'll share my likes, hobbies, and more. Every now and then, I'll even have something interesting to say in a blog post.</p>
<!-- /wp:paragraph -->
<!-- wp:buttons {"layout":{"type":"flex","justifyContent":"center"}} -->
<div class="wp-block-buttons"><!-- wp:button {"className":"is-style-outline"} -->
<div class="wp-block-button is-style-outline"><a class="wp-block-button__link wp-element-button">See My Popular Posts →︎</a></div>
<!-- /wp:button --></div>
<!-- /wp:buttons --></div>
<!-- /wp:group --></div></div>
<!-- /wp:cover -->
Now if you add or edit a new post in WordPress, you should see your pattern listed in the inserter. Click the Patterns tab and select Featured:
You should also be able to see your pattern listed under Appearance > Editor > Patterns in the WordPress admin.
Using PHP to register patterns
Instead of using the 
/patterns folder to auto-register your patterns, you may choose to manually register them via PHP. You can mix and match both registration methods, but an individual pattern must be registered with only one method.
To register block patterns with PHP, you must use the 
register_block_pattern() function. Here is what its signature looks like:
register_block_pattern( 
	string $pattern_name, 
	array $pattern_properties 
): bool
The function accepts two parameters and returns 
true or 
false, depending on whether the pattern was successfully registered:
$pattern_name: A namespaced slug that is unique to your pattern in the form of 
namespace/pattern-name.
$pattern_properties:
content: The block markup for the pattern.
title: A human-readable title that can be translated.
categories: An array of categories in which the pattern belongs.
description: The long description of the registered pattern. Only shown to screen readers.
viewportWidth: The width of the 
<iframe> viewport when previewing the pattern (in pixels).
inserter: Whether to show the pattern in the inserter. Defaults to 
true.
keywords: An array of keywords related to the pattern. Used when a user searches in the inserter.
blockTypes: An array of block types to associate the pattern with.
postTypes: An array of post types in which to limit the pattern. Defaults to all post types.
source: The source for the registered pattern. This should be set to 
theme since the pattern is coming from a theme.
templateTypes: An array of template types the pattern fits with.
When registering patterns via PHP, you should do so on the 
init hook. Now try registering your custom pattern by adding this code in 
functions.php (be sure to add your custom markup to the 
content property):
add_action( 'init', 'themeslug_register_patterns' );
function themeslug_register_patterns() {
	register_block_pattern( 'themeslug/hero', array(
		'title'      => __( 'Hero', 'themeslug' ),
		'categories' => array( 'featured' ),
		'source'     => 'theme',
		'content'    => '<!-- Block pattern goes here. -->'
	) );
}
Conditionally registering patterns
If you need to conditionally register an entire pattern, there are two methods to choose from, depending on how you prefer to register patterns.
Conditionally registering patterns in the /patterns folder
If you have used the auto-registration method of placing your pattern in your theme’s 
/patterns folder, there is no true way to conditionally register it. What you must do in this case is unregister the pattern.
Suppose that you wanted to only make the hero pattern you registered earlier available if the 
core/paragraph block is registered. In a real-world scenario, you’d likely be checking for a third-party block, and the 
core/paragraph block is used only for the sake of this example.
Try this code inside of your 
functions.php file to unregister your previously-registered pattern:
add_action( 'init', 'themeslug_unregister_patterns', 999 );
function themeslug_unregister_patterns() {
	if ( WP_Block_Type_Registry::get_instance()->is_registered( 'core/paragraph' ) ) {
		unregister_block_pattern( 'themeslug/hero' );
	}
}
The above code uses the 
WP_Block_Type_Registry class, which stores all block types that are registered on the server-side with WordPress. Using the class’s 
is_registered() method, you can determine whether a block is registered.
Conditionally registering patterns via register_block_pattern()
If you manually registered your patterns via PHP, you only need to wrap your call to 
register_block_pattern() with your conditional check.
Using the same example as above, try only registering your pattern if the 
core/paragraph block is registered by adding this to 
functions.php:
add_action( 'init', 'themeslug_register_patterns', 999 );
function themeslug_register_patterns() {
	if ( WP_Block_Type_Registry::get_instance()->is_registered( 'core/paragraph' ) ) {
		register_block_pattern( 'themeslug/hero', array(
			'title'      => __( 'Hero', 'themeslug' ),
			'categories' => array( 'featured' ),
			'source'     => 'theme',
			'content'    => '<!-- Block pattern goes here. -->'
		) );
	}
}
Unregistering patterns
There are times when you need to unregister block patterns so that they do not appear in the inserter for users. For example, you may want to remove some of the core WordPress patterns, those added by a parent theme (if you’re building a child theme), or those added by third-party plugins.
When you need to unregister a single block pattern, you’ll use the 
unregister_block_pattern() function:
unregister_block_pattern( string $pattern_name ): bool
Like when registering patterns, you’ll also want to unregister on the 
init hook. Because patterns are generally (but not always) registered with the default priority 
10 on 
init, you’ll want to use a higher priority so that your code runs later.
Try unregistering your custom pattern from earlier by adding this code to your 
functions.php file:
add_action( 'init', 'themeslug_unregister_patterns', 999 );
function themeslug_unregister_patterns() {
	unregister_block_pattern( 'themeslug/hero' );
}
Removing Core patterns
While you can use 
unregister_block_pattern() to unregister individual core WordPress patterns, you can also choose to get rid of all of them by removing support for the core-block-patterns feature.
To remove all core WordPress patterns, add this code to your theme’s 
functions.php file:
add_action( 'after_setup_theme', 'themeslug_remove_core_patterns' );
function themeslug_remove_core_patterns() {
	remove_theme_support( 'core-block-patterns' );
}
Disabling remote patterns
WordPress also automatically loads some patterns remotely from the official Pattern Directory on WordPress.org. There are some situations where you might not want to load these patterns, such as when they don’t match your theme design. You may also want to opt out of calling a remote API on a site that you’re building for a client. Whatever the case, you can disable this by filtering the 
should_load_remote_block_patterns hook.
To disable remote patterns, add this code to your 
functions.php file:
add_filter( 'should_load_remote_block_patterns', '__return_false' );
Pattern categories
WordPress has several block pattern categories that it registers by default:
featured
about
audio (added in WordPress 6.4)
banner
buttons
call-to-action
columns
contact
footer
gallery
header
media
portfolio
posts
query (use 
posts instead)
services
team
testimonials
text
video (added in WordPress 6.4)
It’s generally best to use these default categories for your theme. This keeps a consistent UI that users will be accustomed to. But there are times when you may want to add your own categories or even remove those that are already registered.
In this section of the article, you’ll learn how to both register and unregister custom block pattern categories.
Registering a pattern category
To register a custom category for putting one or more of your patterns into, you must use the 
register_block_pattern_category() function:
register_block_pattern_category( 
	string $category_name, 
	array $category_properties 
): bool
The function accepts two parameters:
$category_name: A unique ID/slug for the category. It’s good practice to prefix this with your theme slug (e.g., 
themeslug-category-name).
$category_properties: An array of properties for defining further data about the category:
label: A human-readable label/title for the category that may be translated.
description: A description for the category that may be translated.
Try adding a new custom pattern category for your theme. Add this code to your theme’s 
functions.php file:
add_action( 'init', 'themeslug_register_pattern_categories' );
function themeslug_register_pattern_categories() {
	register_block_pattern_category( 'themeslug/custom', array( 
		'label'       => __( 'Theme Name: Custom', 'themeslug' ),
		'description' => __( 'Custom patterns for Theme Name.', 'themeslug' )
	) );
}
Now try adding the 
themeslug/custom category to any block pattern:
<?php
/**
 * Title: Hero
 * Slug: themeslug/hero
 * Categories: featured, themeslug/custom
 */
?>
<!-- Your block markup goes here. -->
Any registered patterns for this category will now appear in the inserter and under Appearance > Editor > Patterns (Appearance > Patterns for classic themes):
Unregistering a pattern category
To unregister a registered pattern category, you must use the 
unregister_block_pattern_category() function:
unregister_block_pattern_category( string $category_name ): bool
The function accepts a single parameter:
$category_name: The name (i.e., slug) of the registered category to unregister.
Try adding this code to your 
functions.php to remove the 
themeslug/custom category you registered in the previous step:
add_action( 'init', 'themeslug_unregister_pattern_categories' );
function themeslug_unregister_pattern_categories() {
	register_block_pattern_category( 'themeslug/custom' );
}

Starter Patterns
The WordPress block editor is powerful and can handle many different layouts and designs. However, when building a theme, you must remember that not all of your users will be skilled designers or even have much interest in piecing together their own layouts. This is where starter patterns can be beneficial to them.
WordPress supports two types of starter patterns for pages (or any post type) and templates. This feature lets you create starting points for your theme users to build out their pages and templates with minimal skills.
Starter page patterns
Page patterns let you create custom patterns your theme users can access when adding a new page via Pages > Add New in their WordPress admin. From there, a modal will pop up and show them a selection of patterns if any are registered.
Here is what the screen looks like when creating a new page with the default Twenty Twenty-Four theme installed:
This is a powerful feature because it means that you can provide well-designed starting points for your theme’s users or clients. And they don’t need to build from scratch. They only need to select a pattern, and it will automatically be inserted into the content area. From there, they can make any customizations they want.
How to create a page pattern
Technically, any pattern in your theme can be converted to a page pattern. All you need to do is define the correct parameters to mark it as such. As described in Registering Patterns, there are two available file header fields that you must set to make this happen:
Block Types: Adding 
core/post-content as one of the block types for the pattern tells WordPress that the pattern should be used for the post content.
Post Types: You can add one or more post types (separated by commas) to connect the pattern.
With these two fields combined, you create a starter page pattern. Here is what the file header looks like for a fictional 
/patterns/example-page.php pattern file:
<?php
/**
 * Title: Example Page
 * Slug: themeslug/example-page
 * Categories: page
 * Block Types: core/post-content
 * Post Types: page
 * Viewport width: 1376
 */
?>
<!-- Block code here. -->
And that’s literally all you must do. Define the pattern’s 
Block Types and 
Post Types parameters and you have a starter page pattern.
This will work with any post type that has opted into the block editor, including both the default 
post and 
page post types.
Because page patterns are actually tied to the content, you wouldn’t typically include something like a site header or footer here. The pattern is output as post content.
Starter template patterns
Like page patterns, template patterns give users a starting point when building a new template. The difference is that template patterns work from the Site Editor.
If you visit Appearance > Editor > Templates in your WordPress admin and click the + icon button for creating a new template, you should see a new Add template modal:
From there, you can select the template that you want to create. If the template type has any patterns registered for it, a new Choose a pattern modal will appear, overlaying the template-editing interface.
For example, when choosing the Front Page option with the default Twenty Twenty-Four theme, you will see this:
This gives your theme users a really nice onramp for building templates. It means they don’t have to create everything from the ground up and can get started down the right path.
How to create template type patterns
Unlike page patterns, you will usually not make any of your patterns a template pattern. These are starting points for an entire template, so their use cases are much more limited and specific.
Because template patterns represent an entire template, you would typically include global elements like the header, footer, sidebar, and other sections that your theme’s templates display.
As noted in Registering Patterns, there is a single required header field needed for your template pattern (and one optional field):
Template Types: One or more template types, separated by comma, that the pattern should be associated with.
Inserter: (Optional) Often, you will not want template patterns to be available via the inserter. To disable this, set it to 
no or 
false.
Suppose that you created a pattern that would work well for the Front Page or Home templates. Here is what a fictional 
/patterns/home-template.php file would look like:
<?php
/**
 * Title: Home Template
 * Slug: themeslug/home-template
 * Template Types: front-page, home
 * Viewport width: 1376
 * Inserter: no
 */
?>
<!-- Block code here. -->
From that point, anytime a user attempted to create a new Front Page or Home template from the WordPress Site Editor, they would be presented with your template pattern as a starting point.
Supported template types
The following list includes the templates that you can define via the 
Template Types field, but you can always reference the Template Hierarchy documentation for a full overview of templates:
index
home
front-page
singular
single
page
archive
author
category
taxonomy
date
tag
attachment
search
privacy-policy
404
Using template patterns in templates
When creating custom template patterns, it also makes sense to reuse those patterns within your templates. Why rewrite code?
Imagine that you created a template pattern that would work as both a Home and Index template. It would look like this:
<?php
/**
 * Title: Index Template
 * Slug: themeslug/index-template
 * Template Types: home, index
 * Viewport width: 1376
 * Inserter: no
 */
?>
<!-- Block code here. -->
Now suppose that you included a 
/templates/index.html template in your theme. Instead of adding the code in two places, you can simply call the pattern from the template file:
<!-- wp:pattern {"slug":"themeslug/index-template"} /-->
To learn more about including patterns in templates, check out the Usage in Templates documentation.

Usage in Templates
When building themes, patterns are not merely reusable sections of blocks that users can add to their content. That is a nice feature, but the true power of patterns is using them directly in your theme’s front-end output.
In this article, you will learn both why and how to include patterns in your theme’s templates and template parts.
Why use patterns in templates?
There are two primary reasons to use patterns in your templates:
PHP access: Block templates and template parts are HTML files and you need access to various PHP functions for dynamic functionality. You can learn more about this in the Using PHP in Patterns documentation.
The DRY (Don’t Repeat Yourself) principle: When building any type of software (themes included) you should always reuse code when possible, which means less work for you and fewer potential bugs. Because patterns are reusable groups of blocks, it makes sense to use the pattern instead of rewriting the code in your templates and parts.
This article will primarily focus on the last point. You will learn how to reuse your patterns within your theme’s block templates and template parts.
One of the best use cases is to create patterns of common elements across multiple templates. For example, if your Home, Archive, and Search templates all include the same Query Loop layout, create a pattern for that design and include it in each template.
The Pattern block
As described in Introduction to Patterns, a block pattern is merely one or more blocks that you have registered as a pattern. However, there is also a block named Pattern available in WordPress. You won’t find the Pattern block anywhere in the UI (such as the block inserter). It’s primarily meant to be used in WordPress themes.
Here is what the Pattern block markup looks like:
<!-- wp:pattern {"slug":"namespace/pattern-slug"} /-->
As you can see, it looks just like any other block markup. The big difference is that you must set the 
slug parameter to include a specific pattern. The value must include both the pattern namespace and slug.
Whenever you want to include a pattern within a template or template part, you only need to call the Pattern block.
You can also include patterns registered by WordPress or plugins in templates, not just those from your theme. All you need to do is reference the correct 
slug value when calling the Pattern block.
Adding a pattern to a template
In this section, you will walk through a practical example of including a pattern within a template.
Assume you had a “hero” pattern that you have registered for your theme because you want users to be able to insert it anywhere they need to. But you also want to include this in your Home template by default.
First, register a custom pattern with the 
themeslug/hero, as described in the Registering Patterns documentation. Create a new file named 
hero.php and place it into your theme’s 
/patterns folder with this code:
<?php
/**
 * Title: Hero
 * Slug: themeslug/hero
 * Categories: featured
 */
?>
<!-- wp:cover {"overlayColor":"contrast","isUserOverlayColor":true,"align":"full"} -->
<div class="wp-block-cover alignfull">
	<span aria-hidden="true" class="wp-block-cover__background has-contrast-background-color has-background-dim-100 has-background-dim"></span>
	<div class="wp-block-cover__inner-container">
		
		<!-- wp:heading {"textAlign":"center"} -->
		<h2 class="wp-block-heading has-text-align-center"><?php esc_html_e( 'Welcome to My Site', 'themeslug' ); ?></h2>
		<!-- /wp:heading -->
		<!-- wp:paragraph {"align":"center"} -->
		<p class="has-text-align-center"><?php esc_html_e( 'This is my little home away from home.', 'themeslug' ); ?></p>
		<!-- /wp:paragraph -->
		<!-- wp:buttons {"layout":{"type":"flex","justifyContent":"center"}} -->
		<div class="wp-block-buttons">
			<!-- wp:button {"className":"wp-block-button is-style-outline"} -->
			<div class="wp-block-button is-style-outline"><a class="wp-block-button__link wp-element-button"><?php esc_html_e( 'Button A', 'themeslug' ); ?></a></div>
			<!-- /wp:button -->
		</div>
		<!-- /wp:buttons -->
	</div>
</div>
<!-- /wp:cover -->
This will make the pattern both available to users via the UI and to your theme templates for inclusion.
To include this specific pattern in a template, you need to call it like so:
<!-- wp:pattern {"slug":"themeslug/hero"} /-->
Now try adding it to one of your theme’s templates, such as 
/templates/home.html or 
/templates/index.html below the header. Your template with the pattern code should look similar to this:
<!-- wp:template-part {"slug":"header"} /-->
<!-- wp:pattern {"slug":"themeslug/hero"} /-->
<!-- Some other blocks. /-->
<!-- wp:template-part {"slug":"footer"} /-->
Now test the addition of the pattern in the Site Editor by going to Appearance > Editor > Templates and choosing the template you added it to:
The pattern should also appear on the front end of your site when that template is in use.
From this point, you can use this feature however you need. Whether you’re including a pattern in a template or template part, the process is the same.

Using PHP in Patterns
One of the biggest advantages of patterns over features like templates and template parts is that you can use PHP in them, which opens a world of possibilities for what you can accomplish. However, there are limits on what functionality is available to your patterns.
In this article, you will learn the limitations of the patterns system, when and how you can use PHP, and some of the most common use cases for dynamic functionality.
Patterns are registered on init
When using PHP in patterns, it’s important to understand when the pattern’s block markup is actually compiled versus when it is rendered.
Pattern registration happens on the 
init hook. At this point, WordPress compiles the content of the pattern and saves a copy of it as HTML-based block markup. This allows it to be used in both the editor and the front end. It’s during this registration process where the pattern can execute PHP code.
A pattern’s block markup is not actually rendered until it is used either in the editor or on the front end. However, the block markup is plain HTML at the time it is rendered.
At a practical level, this means that a lot of data is unavailable during the registration process on 
init. Your patterns cannot access things like the global query or post. They also cannot use functions associated with that data. So this means that WordPress functions like 
is_home(), 
is_single(), 
get_post(), and others are simply not ready yet.
For example, this PHP wouldn’t execute correctly in a pattern:
<?php if ( is_page() ) : ?>
	<!-- wp:paragraph -->
	<p><?php the_title(); ?></p>
	<!-- /wp:paragraph -->
<?php endif; ?>
Neither the 
is_page() nor the 
the_title() functions have the global data they need when a pattern is registered, so they won’t work.
If you’re accustomed to building classic themes, this can feel very unintuitive, especially if you’ve been equating PHP-based patterns to classic, PHP-based template parts.
There are other methods for executing PHP at the time of render, such as using the Block Bindings API. But those methods are outside the scope of pattern documentation.
You still have a wide and wonderful range of PHP functions and many WordPress functions available to you. And you’ll learn more about what you can use in the upcoming sections of this article.
An example pattern
For the rest of this article, let’s use a single pattern that begins as mostly HTML. Then, you’ll walk through adding PHP to dynamically handle some portions of it.
Create a new file named 
patterns/hero.php in your theme and put this code into it:
<?php
/**
 * Title: Hero
 * Slug: themeslug/hero
 * Categories: featured
 */
?>
<!-- wp:cover {"overlayColor":"contrast","isUserOverlayColor":true,"align":"full"} -->
<div class="wp-block-cover alignfull">
	<span aria-hidden="true" class="wp-block-cover__background has-contrast-background-color has-background-dim-100 has-background-dim"></span>
	<div class="wp-block-cover__inner-container">
		
		<!-- wp:heading {"textAlign":"center"} -->
		<h2 class="wp-block-heading has-text-align-center">Welcome to My Site</h2>
		<!-- /wp:heading -->
		<!-- wp:paragraph {"align":"center"} -->
		<p class="has-text-align-center">This is my little home away from home.</p>
		<!-- /wp:paragraph -->
		<!-- wp:buttons {"layout":{"type":"flex","justifyContent":"center"}} -->
		<div class="wp-block-buttons">
			<!-- wp:button {"className":"wp-block-button is-style-outline"} -->
			<div class="wp-block-button is-style-outline"><a class="wp-block-button__link wp-element-button">Button A</a></div>
			<!-- /wp:button -->
			<!-- wp:button {"className":"wp-block-button is-style-outline"} -->
			<div class="wp-block-button is-style-outline"><a class="wp-block-button__link wp-element-button">Button B</a></div>
			<!-- /wp:button -->
		</div>
		<!-- /wp:buttons -->
	</div>
</div>
<!-- /wp:cover -->
If you insert it the pattern into the editor, it should look like this:
Internationalizing text in patterns
One of the primary use cases for block patterns is internationalizing text (making it ready for translation). For example, if you have text in a template or template part, the only way to internationalize that text is to move it into a pattern, where you have full access to PHP.
Because pattern files are just PHP, you can use any of the internationalization functions within WordPress. In the below example, you’ll use 
esc_html_e() to both escape the text for security and make it ready for translators.
Let’s look at the Heading block from your Hero pattern:
<!-- wp:heading {"textAlign":"center"} -->
<h2 class="wp-block-heading has-text-align-center">Welcome to My Site</h2>
<!-- /wp:heading -->
As you can see, the “Welcome to My Site” text in the Heading block is not internationalized. When shipping your theme to users all around the world who speak many different languages, it’s important to ensure this text can be translated.
To internationalize the Heading block’s text, you must wrap it in an internationalization function (
esc_html_e() in this case). So you’d change the block markup to look like this:
<!-- wp:heading {"textAlign":"center"} -->
<h2 class="wp-block-heading has-text-align-center"><?php esc_html_e( 'Welcome to My Site', 'themeslug' ); ?></h2>
<!-- /wp:heading -->
There are three other places where you should also make these changes. The first is to the Paragraph block text, and then the two Button blocks. Your new 
patterns/hero.php file should look like this:
<?php
/**
 * Title: Hero
 * Slug: themeslug/hero
 * Categories: featured
 */
?>
<!-- wp:cover {"overlayColor":"contrast","isUserOverlayColor":true,"align":"full"} -->
<div class="wp-block-cover alignfull">
	<span aria-hidden="true" class="wp-block-cover__background has-contrast-background-color has-background-dim-100 has-background-dim"></span>
	<div class="wp-block-cover__inner-container">
		
		<!-- wp:heading {"textAlign":"center"} -->
		<h2 class="wp-block-heading has-text-align-center"><?php esc_html_e( 'Welcome to My Site', 'themeslug' ); ?></h2>
		<!-- /wp:heading -->
		<!-- wp:paragraph {"align":"center"} -->
		<p class="has-text-align-center"><?php esc_html_e( 'This is my little home away from home.', 'themeslug' ); ?></p>
		<!-- /wp:paragraph -->
		<!-- wp:buttons {"layout":{"type":"flex","justifyContent":"center"}} -->
		<div class="wp-block-buttons">
			<!-- wp:button {"className":"wp-block-button is-style-outline"} -->
			<div class="wp-block-button is-style-outline"><a class="wp-block-button__link wp-element-button"><?php esc_html_e( 'Button A', 'themeslug' ); ?></a></div>
			<!-- /wp:button -->
			<!-- wp:button {"className":"wp-block-button is-style-outline"} -->
			<div class="wp-block-button is-style-outline"><a class="wp-block-button__link wp-element-button"><?php esc_html_e( 'Button B', 'themeslug' ); ?></a></div>
			<!-- /wp:button -->
		</div>
		<!-- /wp:buttons -->
	</div>
</div>
<!-- /wp:cover -->
Using images and other assets
Adding dynamic URLs for images and other assets is another important feature of patterns. Because you have PHP access, you can use functions like 
get_theme_file_uri() to output an image URL that’s bundled with your theme, for example.
Try adding an image background to your “hero” pattern’s Cover block. If you need an image, try grabbing one from the WordPress Photo Directory (the example below uses this Nepal night scene photo).
Download an image and save it to your theme’s 
/assets/images folder (or a folder of your choice) and name it 
hero-background.jpg.
Then open your pattern in the editor and upload the image as the background for the Cover block in your Hero pattern, which should look like this:
If you copy the blocks that make up the pattern, you’ll notice that you have two instances of the image URL in your pattern code. It will be a hardcoded URL similar to this:
http://localhost/wp-content/uploads/2023/10/hero-background.jpg
You need to change both of those instances so that they point to the image that is located in your theme’s 
/assets/images folder. For this, you need do two things:
Get the correct URL using a function like 
get_theme_file_uri().
Escape the URL so that it’s safe for output with 
esc_url().
Change the hard coded image URLs to this:
<?php echo esc_url( get_theme_file_uri( 'assets/images/hero-background.jpg' ) ); ?>
Your final pattern code should look like this (note that this example includes internationalized text as explained in the previous section):
<?php
/**
 * Title: Hero
 * Slug: themeslug/hero
 * Categories: featured
 */
?>
<!-- wp:cover {"url":"<?php echo esc_url( get_theme_file_uri( 'assets/images/hero-background.jpg' ) ); ?>","id":3838,"dimRatio":50,"overlayColor":"contrast","align":"full"} -->
<div class="wp-block-cover alignfull">
	<span aria-hidden="true" class="wp-block-cover__background has-contrast-background-color has-background-dim"></span>
	<img class="wp-block-cover__image-background wp-image-3838" alt="" src="<?php echo esc_url( get_theme_file_uri( 'assets/images/hero-background.jpg' ) ); ?>" data-object-fit="cover"/>
	<div class="wp-block-cover__inner-container">
		
		<!-- wp:heading {"textAlign":"center"} -->
		<h2 class="wp-block-heading has-text-align-center"><?php esc_html_e( 'Welcome to My Site', 'themeslug' ); ?></h2>
		<!-- /wp:heading -->
		<!-- wp:paragraph {"align":"center"} -->
		<p class="has-text-align-center"><?php esc_html_e( 'This is my little home away from home.', 'themeslug' ); ?></p>
		<!-- /wp:paragraph -->
		<!-- wp:buttons {"layout":{"type":"flex","justifyContent":"center"}} -->
		<div class="wp-block-buttons">
			<!-- wp:button {"className":"wp-block-button is-style-outline"} -->
			<div class="wp-block-button is-style-outline"><a class="wp-block-button__link wp-element-button"><?php esc_html_e( 'Button A', 'themeslug' ); ?></a></div>
			<!-- /wp:button -->
			<!-- wp:button {"className":"wp-block-button is-style-outline"} -->
			<div class="wp-block-button is-style-outline"><a class="wp-block-button__link wp-element-button"><?php esc_html_e( 'Button B', 'themeslug' ); ?></a></div>
			<!-- /wp:button -->
		</div>
		<!-- /wp:buttons -->
	</div>
</div>
<!-- /wp:cover -->
foreach() loops
You have access to nearly every PHP function and feature at your disposal, and many things will undoubtedly be useful to you as you build themes. But 
foreach() loops are likely one of the features that you will often reach for.
foreach() loops are particularly useful in patterns that have repeated blocks. For example, in your 
patterns/hero.php file, you have a set of two Button blocks:
<!-- wp:button {"className":"wp-block-button is-style-outline"} -->
<div class="wp-block-button is-style-outline"><a class="wp-block-button__link wp-element-button"><?php esc_html_e( 'Button A', 'themeslug' ); ?></a></div>
<!-- /wp:button -->
<!-- wp:button {"className":"wp-block-button is-style-outline"} -->
<div class="wp-block-button is-style-outline"><a class="wp-block-button__link wp-element-button"><?php esc_html_e( 'Button B', 'themeslug' ); ?></a></div>
<!-- /wp:button -->
One of the foundational principles of development is DRY (Don’t Repeat Yourself). And this code breaks that principle. With a single 
foreach() loop, you can create the block markup once and loop through it.
First, you need an array of items to loop through, which is the Button content itself. At the top of your 
patterns/hero.php file before the closing 
?> tag, add an array of labels:
$buttons = array(
	__( 'Button A', 'themeslug' ),
	__( 'Button B', 'themeslug' )
);
Then replace the markup for your two Button blocks with this code:
<?php foreach ( $buttons as $button ) : ?>
	<!-- wp:button {"className":"wp-block-button is-style-outline"} -->
	<div class="wp-block-button is-style-outline"><a class="wp-block-button__link wp-element-button"><?php echo esc_html( $button ); ?></a></div>
	<!-- /wp:button -->
<?php endforeach; ?>
Your full 
patterns/hero.php file should now look like the following (note this includes both the internationalized text and dynamic image example code from earlier):
<?php
/**
 * Title: Hero
 * Slug: themeslug/hero
 * Categories: featured
 */
$buttons = array(
	__( 'Button A', 'themeslug' ),
	__( 'Button B', 'themeslug' )
);
?>
<!-- wp:cover {"url":"<?php echo esc_url( get_theme_file_uri( 'assets/images/hero-background.jpg' ) ); ?>","id":3838,"dimRatio":50,"overlayColor":"contrast","align":"full"} -->
<div class="wp-block-cover alignfull">
	<span aria-hidden="true" class="wp-block-cover__background has-contrast-background-color has-background-dim"></span>
	<img class="wp-block-cover__image-background wp-image-3838" alt="" src="<?php echo esc_url( get_theme_file_uri( 'assets/images/hero-background.jpg' ) ); ?>" data-object-fit="cover"/>
	<div class="wp-block-cover__inner-container">
		
		<!-- wp:heading {"textAlign":"center"} -->
		<h2 class="wp-block-heading has-text-align-center"><?php esc_html_e( 'Welcome to My Site', 'themeslug' ); ?></h2>
		<!-- /wp:heading -->
		<!-- wp:paragraph {"align":"center"} -->
		<p class="has-text-align-center"><?php esc_html_e( 'This is my little home away from home.', 'themslug' ); ?></p>
		<!-- /wp:paragraph -->
		<!-- wp:buttons {"layout":{"type":"flex","justifyContent":"center"}} -->
		<div class="wp-block-buttons">
			<?php foreach ( $buttons as $button ) : ?>
				<!-- wp:button {"className":"wp-block-button is-style-outline"} -->
				<div class="wp-block-button is-style-outline"><a class="wp-block-button__link wp-element-button"><?php echo esc_html( $button ); ?></a></div>
				<!-- /wp:button -->
			<?php endforeach; ?>
		</div>
		<!-- /wp:buttons -->
	</div>
</div>
<!-- /wp:cover -->
At this point, your pattern is fully dynamic. As you dive deeper into pattern development, you’ll come up with even more use cases for using PHP. Think of this article as just the foundation that you’ll build from.

Required Theme Files
Block theme: See Create a Block Theme for building a block theme
Classic themes must include the required theme files. These files must follow template file standards set by the themes team. For Classic themes, additional standard template files are recommended to use. Learn more about the Organizing Theme Files.
Classic Themes Required Theme Files
style.cssYour theme’s main stylesheet file. This file will also include information about your theme, such as author name, version number, and plugin URL, in its header.
index.phpThe main template file for your theme. This will be the template for the homepage on your site unless a static front page is specified. If you only include this template file, it must include all functionality of your theme. However, you can use as many relevant template files as you want in your theme.
comments.phpThe comment template which is included wherever comments are allowed. This file should provide support for threaded comments and trackbacks, and should style author comments differently than user comments. See the Comments page for more information.
screenshotIn the WordPress.org theme directory, the screenshot acts as a visual indicator of what your theme looks like. It is visible both in the web view and in the admin dashboard. The screenshot must not be bigger than 1200 x 900px.
While these files are the only files required by the theme review team for acceptance into the WordPress.org theme directory, you may use other template files. Of course, any file mentioned in the tutorial in this handbook may be used in your theme.

Submitting Your Theme to WordPress.org
Before themes are added to the WordPress Theme Directory, they are closely reviewed by the Themes team to make sure they adhere to basic guidelines. This review ensures that WordPress users across the globe can download themes that are high quality and secure.
Need Help?
If you have theme development questions, please post them in the Developing with WordPress forum. Volunteers from around the world are ready to assist you with the development of your theme.
Guidelines
Make sure you review the Theme Review Guidelines before uploading a theme. If you have questions about these guidelines, you can ask them in the #themes channel in Slack. Anyone with a WordPress.org account can access the Making WordPress Slack.
Testing With Sample Data
The WordPress Themes Team will be reviewing your theme using the sample data from the Theme Unit Test. Before uploading your theme for review, please test it with this sample export data.
Uploading Your Theme
When you are ready to submit your theme for review, please upload your theme ZIP at Themes > Upload. Future updates are to be uploaded via the same page.
More information about the theme review process is available on the Themes Team website.

Testing
If you’ve followed this handbook, you’ll already have a good grasp on the testing required before submitting your theme to the WordPress.org theme directory. If you haven’t, this page will give you a quick refresher.
Testing is incredibly important before releasing a theme. You may have built the most beautiful WordPress theme, but if it breaks when someone tries to comment or insert an image, your theme isn’t ready for real world usage.
Before testing your theme, make sure you’ve setup a development environment. There are a number of ways to setup your environment, many of which are documented on the Setting up a Development Environment page.
Theme Unit Test
After you’ve setup your development environment, you’ll need test content to test your theme with. While you can create your own test content, the theme review team has created the Theme Unit Test, which includes many different types of content. This will help ensure that your theme works in circumstances you may not have anticipated.
The Theme Unit Test is a WordPress export file that can be imported into any WordPress installation by using the WordPress Importer. You should import it into your local development environment.
WordPress Settings
Making tweaks and changes to your WordPress installation is another good way to ensure that you’ve built your theme to handle numerous scenarios. Use the following settings to test your theme.
General
Set the Site Title to something long and set the Tagline to something even longer. These settings will test how your theme handles edge cases for site titles and taglines.
Reading
Set “Blog pages show at most” to 5. This setting will ensure that index/archive pagination is triggered.
Discussion
Enable “Threaded Comments” at least 3 levels deep. This setting will facilitate testing of your theme’s comment list styling.
Enable “Break comments into pages” and set 5 comments per page to test the pagination and styling of comments.
Media
Remove the values for the large size of media to test the theme’s 
$content_width setting.
Permalinks
Change the permalink setting a few times to ensure your theme can handle various URL formats.
For more setup instructions, take a look at the Theme Unit Test page in the WordPress Codex.
WordPress Beta Tester
WordPress releases happen three times a year. It’s a good idea to test your theme against the next version of WordPress so you can anticipate issues when the next version is released. This can be done easily with the WordPress Beta Tester plugin. The plugin makes it easy to download either the latest nightly version of WordPress or the latest branch version (for minor bugfix releases). This is especially useful when anticipating a new major release or developing for an upcoming feature.
Testing and debugging tools
Theme Check
Each theme goes through an automated check before a reviewer even sees it. If there are any immediate problems with the theme, identified by the automated check, the theme will be rejected with notes on how to resolve the issues. The Theme Check plugin adds a dashboard link under Appearance so you can run the exact same checks that WordPress.org does right from your administration panel. Doing this prior to uploading your theme lets you know what needs to be addressed prior to submission. Running the check will give you a list of any warnings your theme has generated and what items are required for the theme to be accepted in the WordPress.org theme directory, as well as any recommended items that may be missing from your theme.
Developer
The Developer plugin is really just a tool to automatically download and install some of the plugins you’ll want when developing your theme. Some of the ones discussed in this handbook will already be installed and active. Others you can install as soon as you activate the plugin.
Debug Bar
Debug Bar pushes all debug messages to a separate page where they are listed in an easy-to-read layout and organized by type of message. There are also a number of other plugins that add on to Debug Bar, extending its features or adding more information.
Log Deprecated Notices
Log Deprecated Notices displays a list of the deprecated function notices in your theme and where the code can be found. This should be run, at minimum, after every major release of WordPress, so you can resolve and remove any deprecated code and functions from your theme.
Browser testing
When submitting your theme to WordPress.org, it’s expected that it works well in modern browsers and at any resolution. You should test your theme against a number of popular browsers before submitting, both mobile and desktop. Many browsers have built-in features making it easy to test, for example the Chrome Developer Tools, Firefox Developer Tools, and the Microsoft Edge tools. Note that Internet Explorer is no longer supported by WordPress since 5.8 release.
Validation
Likewise, your theme should use valid HTML5 and CSS code. There are a variety of tools that will test your site for valid code, include this HTML5 validator and this CSS validator.

Theme Review Guidelines
The WordPress Themes Team provides and maintains the theme review guidelines as part of their task as WordPress Contributors and Developers for the WordPress Theme Directory. Some of these guidelines are required before themes are included in the theme directory. Other guidelines are recommendations for best practices in developing your theme and making it available to as many people as possible. This handbook uses both recommendations and requirements from the theme review guidelines to ensure the theme you develop is accessible to everyone.
The requirements for being included in the WordPress.org theme directory can be found here.
Get Involved
The WordPress Themes Team is open to anyone and is a great way to get a better understanding of how themes are developed. To become a member of the WordPress Themes Team, read through the WordPress Themes Team’s site.

Updating Your Theme
There are two ways to update your theme, by uploading a Zip file or using subversion (SVN).
Uploading a Zip file
While your theme is in the queue and waiting for review, you can update your theme by uploading a Zip file. Just as you initially uploaded. Be sure to update the version number on style.css before uploading.
Updating the version number will NOT change the queue position of your theme while waiting for the review.
If you already have your themes in the repository, you can either update by uploading a Zip file or via SVN.
Subversion GUI clients
Several GUI clients are available for Windows users. TortoiseSVN is one of the popular Free clients. SmartSVN is a paid application that works on Windows, Linux, and macOS.
For Mac users, SVN helps streamline the automation process, including removing 
.DS_Store and 
__MACOSX hidden files and folders that often trigger the theme check errors.
Important notes:
(1) Directory naming guidelines
The theme author must create a new directory before uploading the theme. It is important to name the new directory with the new version number. For example, if the current theme is version 
1.0.1, the name for the new directory must be*
1.0.2*.
(2) Version numbering
Version numbering must follow a standard version naming convention. New version must be higher than the current version. For example, if your current theme is 
1.2.3, the new version must be 
1.2.4.
(3) SVN is not a development tool
Unlike Github, SVN is not a development tool. You should upload your theme only when you are ready to release a new version. Once you commit, the changes cannot be overwritten. If you find a mistake, even a small typo, there is no way to make changes. The only way to make corrections is to create another directory with a newer version number and upload it again.
Uploading your themes using SVN on MacOS
What you will need
MacOS
VS code
SVN extension for VS code
To check whether you have svn installed, type 
svn --version in the terminal.
(1) Create a copy of the repository on your local machine. Replace /NameOfYourTheme/ with your theme name. 
svn co https://themes.svn.wordpress.org/NameOfYourTheme/
For example, if your theme name is Hello World,
use 
svn co https://themes.svn.wordpress.org/hello-world/
Tips: If you are not sure about the exact name of your theme (e.g. hyphen, underscore), you can find it at this link.
(2) The next step is to create a new directory and copy all theme files, including the history from the current version of the theme. In the example below, we are creating a new directory 1.0.2, and copying all files from the version 1.0.1. 
svn cp 1.0.1 1.0.2
(3) Make changes to your theme.
Note: Make sure to update the version number on style.css, and the changelog on readme.txt
(4) Remove .DS_Store hidden file. 
find . -name ".DS_Store" -print -delete
(5) Next, remove 
__MACOSX folder. 
rm -R __MACOSX
(6) Finally, you are ready to commit.
svn commit -m “Fix typo on readme.txt”
Note: Once you commit, there is no way to change or modify what you just committed. If you find a mistake, Repeat the process from step 2.
What to expect next
Once you successfully upload the new update, you will receive a confirmation email from WordPress.org. It may take some time to reflect on the WordPress.org directory.

Writing Documentation
Documentation is important for themes as it provides a way for users to understand what a theme does and does not support. Likewise, documenting the code of your theme will make it easier for other theme developers to customize your theme, likely with a child theme.
Here’s a list of requirements and recommendationsfor your theme’s documentation.
Themes are required to provide end-user documentation of any design limitations or extraordinary installation/setup instructions.
Themes are required to include a readme.txt file, using the plugin directory’s readme.txt markdown format. New themes need to follow this rule as of October 25th, 2018. Old themes have a 6 months grace time from this date. Since WordPress 5.8 theme readme files are not parsed for requirements. This means that headers 
Requires PHP and 
Requires at least are going to be parsed from theme’s 
style.css file.

Introduction to Templates
Like nearly all content management systems, WordPress uses a templating system to handle the output of content on the front end of a website. In modern block themes, templates are HTML files with block markup.
In this document, you will learn how the templating system in WordPress works. After that, you can jump ahead to the more detailed Templates and Template Parts documentation.
What are templates?
In a nutshell, templates take dynamic data and wrap it into structured HTML markup, which is then sent to the browser. It is not a particularly revolutionary concept, and it is one that nearly every website system with dynamic data uses.
 The templating system in WordPress does a few important things:
Parses block markup, which is used to reference static and dynamic data.
Retrieves dynamic data (e.g., post content, site options, etc.) from the database.
Sends the resulting HTML to the visitor’s browser.
The major difference between WordPress and most other platforms is the inclusion of block markup. Block theme templates are made entirely of blocks, which can both represent static or dynamic data. The WordPress templating system parses these blocks to ensure they output the correct content when it is sent to the visitor’s browser.
Another thing that WordPress does well is provide a visual interface to build or customize templates directly from the admin:
The Site Editor also lets your theme’s users overwrite your block templates and parts from within the administration interface. Any changes that users make are saved in their site’s database. These customizations are stored the same way in the database as they are in template files: as block markup.
Templates vs. plain HTML
If you’ve already learned some basic HTML, you’ve probably built out a webpage or two. But it can be very hard to build out a full website with HTML because you must constantly update every file anytime you make a global change across the entire site.
This is because HTML is a document language. It does not know how to handle dynamic data, nor can it be used to dynamically load reusable pieces of code.
Technically, block templates are 
.html files. However, they contain specialized block markup that is parsed by WordPress’ templating system, which is built in PHP (on the front end) and JavaScript (in the editor). Using this system, blocks can be dynamic, despite existing within 
.html files.
Dynamic data
The major difference between a template and writing plain HTML files is that templates have the ability to insert dynamic data. Let’s look at an example of what this would look like if you were building your website from scratch and not using a CMS like WordPress.
Suppose you wanted to output your site title in plain HTML. You would traditionally wrap it in an 
<h1> tag and manually type your site name:
<h1>Your Website Name</h1>
With WordPress, you don’t need to know the correct HTML or the name of the site. Because a theme can be used on any WordPress site, the site title is dynamic data that will be different from one site to the next.
To output the correct site title and its associated HTML in a block theme, you add the block markup instead:
<!-- wp:site-title /-->
By using the block markup, your theme will work anywhere WordPress is installed.
Reusability
One of the principles of good web design is DRY (Don’t Repeat Yourself). When building websites with plain HTML, you must recode all of that HTML for every single page of the site.
For example, most website headers and footers are exactly the same across every page of the site. So it doesn’t make sense to repeat that code for every page. A template system lets you write the code once and reuse it everywhere.
In WordPress, these smaller, reusable sections of a template are called template parts (or simply, parts).
If you were to create a template part named 
header.html, you could include it using the correct block markup in any template:
<!-- wp:template-part {"slug":"header","tagName":"header"} /-->
This lets you reuse the header part in all of your templates, but you only need to create the 
header.html file once.
Block markup
Templates and template parts are files that are made entirely of block markup that represents individual blocks and their settings. WordPress parses this block markup and translates it to its final HTML markup, which can be understood by web browsers.
Unlike classic themes, WordPress automatically outputs some standard HTML elements for block themes.  This includes the wrapping 
<html> and 
<body> tags, 
<head>, and an outer 
<div class="wp-site-blocks">. WordPress and plugins also automatically output meta, styles, and scripts. In comparison to classic themes, block themes are not responsible for adding PHP hooks.
Block markup is technically valid HTML. WordPress uses a custom HTML comment syntax with a standardized format for the markup.
Let’s take a look at a fictional block’s markup in a template:
<!-- wp:namespace/slug {"align":"full"} /-->
As you can see, the code is wrapped with an opening 
<!-- and closing 
/--> HTML comment tag. This tells WordPress to look for block markup. The markup can then be broken down into a four parts:
Prefix: The 
wp: prefix tells WordPress that this is a block that needs to be parsed and not just an ordinary HTML comment. This is necessary for core and third-party blocks.
Namespace: The namespace for the block to parse.
Slug: The slug for the block to parse.
Block Settings: Valid JSON code that represents the block’s settings.
When working with core WordPress blocks, you do not use the block namespace. For example, the 
core/site-title block doesn’t include the preceding 
core/ when called:
<!-- wp:site-title /-->
References to third-party blocks must include the namespace.
How to create block markup
You could certainly learn to manually write all of the block markup for your theme by hand. But it can be tough to remember all of the possible block settings, and it is also easy to make an error, resulting in a broken website.
Instead, when building block templates, you will almost always want to build via the block editor and either save directly in the database or copy the block markup into your theme’s template files.
The easiest way to build an entire template is to do so via Appearance > Editor > Templates in the WordPress admin. Here is a look at the Twenty Twenty-Three’s Home template from that screen:
You can customize the template entirely using the visual Site Editor by adding, moving, or deleting blocks. You can also adjust individual block settings.
Once your template is designed just like you want, you click the Options button (⋮ icon) in the toolbar and select the Code Editor option. This will give you the block markup for your template. From there, copy and paste it into your template file:
In the case of the Home template, you would paste the block markup in the 
/templates/home.html template of your theme.
Of course, you only need to do this if you plan on distributing the theme to other people. If this is your own site, you can save the template from that screen, and it will be saved to the database, overwriting the 
/templates/home.html template file.
Another technique that some theme authors employ is to build from either the Post/Page Editor or Template Editor. Sometimes, they will create certain smaller sections to copy and paste directly into their templates or template parts.
To copy blocks from the Post Editor, select the blocks that you want to use and click the Options button (⋮ icon) from the block-editing toolbar. Then click the Copy button from the dropdown:
From there, you can paste the copied code into your template or template part file. You can also switch to the Code Editor mode from this screen just like in the Site Editor and copy block markup in the same way.
The relationship between templates and parts
Templates represent the overall HTML output that gets sent to the browser. An easy way to think of these is as “top-level templates” because they are the top, outermost level of the template system.
Template parts are partial templates that live within top-level templates. Parts make it easy to include reusable sections without having to recreate the block markup for each of the templates.
In your theme, your templates and template parts will be located in the 
/templates and 
/parts folders, respectively. Here is example of what that structure may look like:
parts/
footer.html
header.html
templates/
404.html
archive.html
index.html (required)
singular.html
Let’s look at an example of an archive template (
archive.html) and its block markup:
<!-- wp:template-part {"slug":"header","tagName":"header"} /-->
<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
<main class="wp-block-group">
	<!-- wp:template-part {"slug":"loop","align":"full"} /-->
</main>
<!-- /wp:group -->
<!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->
This template basically behaves as a wrapper that includes three template parts:
/parts/header.html
/parts/loop.html
/parts/footer.html
This is not the technique that all block themes use, but it is a common practice. Whenever you have code that is repeated across multiple templates, it’s generally a good idea to copy that code into a template part file and include it in your top-level templates.
At this point, you’ve only been learning about templates at an overarching high level. Now it’s time to dive more deeply into the templating system and how each piece of it works. For your next steps, follow along with these docs:
Templates
Template Parts

Template Hierarchy
As covered in the Templates documentation, templates are reusable files that are used to generate the document structure of pages on your WordPress site. WordPress’ template loader determines which template file should be loaded on any given URL.
This document explains how WordPress’ template loader uses the queried information for a page to build a template hierarchy. Then it covers what the valid templates are for the hierarchy.
Overview
When a visitor lands on any page on a WordPress site, WordPress uses the query string to decide which template should be used to display the page. The query string contains data from the URL that helps make this determination.
With this data available, WordPress searches through the template hierarchy until it finds a matching template file. There are generally three potential areas that WordPress might look for a block template within the hierarchy (in order of priority):
User-created templates stored under the 
wp_template post type in the database.
Templates located in a child theme’s 
/templates folder (if child theme is active).
Templates in the theme’s 
/templates folder.
Your theme can package as many or as few templates as needed to achieve your theme design. The 
index.html template is the only required template file for a block theme.
Visual overview
This diagram shows which template files are called to generate a WordPress page based on the template hierarchy:
The template hierarchy by query type
In WordPress, there is not technically a single template hierarchy. It’s best to think of the hierarchy by the type of page being queried. For example, if the front page is being queried, then it will use the front page template hierarchy.
Below, you will find each template hierarchy broken down by its query type (and some subtypes). This will help you determine which template files to include in your theme.
Front page hierarchy
The Front Page template hierarchy is unique among templates and can change drastically based on what the user has chosen for their Front page displays setting under Settings > Reading in the admin.
If Your latest posts is chosen for the Front page displays setting, the hierarchy is:
front-page.html
Falls back to the Home template hierarchy
If A static page is chosen for the Front page displays setting, the hierarchy is:
front-page.html
Falls back to the Page template hierarchy
Keep in mind that the 
front-page.html template always takes precedence, regardless of the Front page displays setting. It is only the templates lower in the hierarchy that are affected by it.
Home hierarchy
Despite its name, the Home template is not always used for the homepage of a site. Technically, it refers to the page where your latest blog posts are shown (i.e., the blog posts index).
Like the Front Page template hierarchy, the Home template also depends on the Front page displays setting under Settings > Reading in the admin.
If Your latest posts is chosen for the Front page displays setting, this hierarchy will be applied to the front page of the site:
front-page.html
home.html
index.html
If A static page is chosen for the Front page displays setting and a page is selected for Posts page setting, the Home template hierarchy applies to the selected posts page (it does not apply to the front page in this case). The hierarchy in this scenario is:
home.html
index.html
Some history: The term “home” goes back to WordPress’ earliest days when it was only a blogging system and the only thing that appeared on the site’s front page was blog posts. While WordPress has evolved to allow anything on the front page, the “home” terminology was retained to refer to the blog posts index. And the “front page” terminology was used to refer to the site’s front page.
Singular hierarchy
When a visitor lands on a single post, page, attachment page, or entry from a custom post type, WordPress attempts to locate a template based on the queried post for that view.
All singular templates can utilize a custom template, which you’ll see listed as 
{custom_template}.html in the sub-sections below. These almost always sit at the top of the hierarchy. For more information on creating custom templates, check out the “Custom Templates” section of the main Templates documentation.
Single hierarchy
The Single template hierarchy is fired when a visitor lands upon a single post or a single entry from a custom post type. The following hierarchy is used to determine the template:
{custom-template}.html
single-{post_type}-{post_name}.html
single-{post_type}.html
single.html
singular.html
index.html
A custom post type of 
product with a post name (i.e., slug) of 
blue-shirt would use this hierarchy:
{custom-template}.html
single-product-blue-shirt.html
single-product.html
single.html
singular.html
index.html
The core WordPress 
page and 
attachment post types are special cases and are handled differently from the default Single template hierarchy. See the below Page and Attachment sections for more details.
Page hierarchy
The Page template hierarchy fires when someone visits a single page on your website. This hierarchy is used to determine the template:
{custom-template}.html
page-{post_name}.html
page-{post_id}.html
page.html
index.html
A page with a post name (i.e., slug) of 
about-me and an ID of 
200 would use this hierarchy:
{custom-template}.html
page-about-me.html
page-200.html
page.html
index.html
Attachment (media) hierarchy
When visiting the singular views for attachments (media file pages), WordPress prepends the default Single template hierarchy with some additional templates. This is the Attachment template hierarchy:
{mime_type}-{sub_type}.html
{sub_type}.html
{mime_type}.html
attachment.html
Falls back to the default Single template hierarchy
If you had an attachment with the 
image/jpeg mime type, the 
image piece of that would be considered the 
mime_type, and the 
jpeg part would be the 
sub_type.
Suppose you had an attachment with the 
image/jpeg type and the post name (i.e., slug) of 
red-bird. The full attachment template hierarchy would be:
image-jpeg.html
jpeg.html
image.html
attachment.html
{custom-template}.html
single-attachment-red-bird.html
single-attachment.html
single.html
singular.html
index.html
As of WordPress 6.4, attachment pages are no longer enabled by default on new installations. Users can enable them with a plugin, so it is still good practice to test your theme and ensure it properly displays content when viewing an attachment page.
Privacy Policy page hierarchy
The Privacy Policy page in WordPress is a special case in comparison to other pages. WordPress will look for a 
privacy-policy.html template before looking at the normal page template hierarchy. For the Privacy Policy page, the following is the template hierarchy:
privacy-policy.html
Falls back to the Page template hierarchy
Archive hierarchy
Archives in WordPress display posts that are grouped by either some type of metadata (e.g., date, author, post type) or by a taxonomy term (category, tag).
Taxonomy term hierarchy
When working with publicly-rendered taxonomies, each term within the taxonomy will have its own archive page. The taxonomy term template hierarchy is:
taxonomy-{taxonomy_slug}-{term_slug}.html
taxonomy-{taxonomy_slug}.html
taxonomy.html
archive.html
index.html
If you had a taxonomy with the slug of 
location and a term within that taxonomy with the slug of 
alabama, the template hierarchy would become:
taxonomy-location-alabama.html
taxonomy-location.html
taxonomy.html
archive.html
index.html
The core WordPress 
category and 
post_tag taxonomies do not use the taxonomy term template. See the Category and Tag sections below for more details.
Category hierarchy
When a visitor clicks on a category link and views the category archive page, the following template hierarchy is used:
category-{slug}.html
category-{id}.html
category.html
archive.html
index.html
When viewing a category archive where the category slug is 
news and the category ID is 
123, the template hierarchy becomes:
category-news.html
category-123.html
category.html
archive.html
index.html
Tag hierarchy
When a visitor clicks on a tag link and views a tag archive page, the following template hierarchy is used:
tag-{slug}.html
tag-{id}.html
tag.html
archive.html
index.html
When viewing a tag archive where the tag slug is 
flowers and the tag ID is 
456, the template hierarchy becomes:
tag-flowers.html
tag-456.html
tag.html
archive.html
index.html
Post type archive hierarchy
A custom post type can have a publicly-facing archive page, which essentially serves as an index page for that post type, listing its latest posts by default (though, this can be filtered and changed). When a visitor views a post type archive, the template hierarchy is:
archive-{post_type}.html
archive.html
index.html
If you had a post type with the slug of 
portfolio_project, its hierarchy would be:
archive-portfolio_project.html
archive.html
index.html
The core WordPress 
post post type uses the Home template hierarchy, and the default 
page and 
attachment post types do not have archive views.
Author hierarchy
Despite its use of the term “author,” an author archive is one part user profile and one part post author archives. An archive URL is generated for all users on a WordPress site, regardless of whether they have published posts. But the intent of the author template is generally to display some metadata about the user and list their posts.
When visiting an author archive page on the front end of a site, this is the template hierarchy:
author-{user_nicename}.html
author-{user_id}.html
author.html
archive.html
index.html
When visiting an author archive page for a user with a nicename of 
matt and an ID of 
333, the author archive template hierarchy becomes:
author-matt.html
author-333.html
author.html
archive.html
index.html
Date hierarchy
When viewing a date or datetime-based archive page (e.g., yearly, monthly, weekly archives), The template hierarchy is:
date.html
archive.html
index.html
Search hierarchy
The search template hierarchy is used when viewing the search results on your website. It is similar to archives in that it lists multiple posts, but it is not technically an archive page. The template hierarchy for search results is:
search.html
index.html
404 (not found) hierarchy
When a URL is visited on the website that doesn’t exist, WordPress looks for a 404 template, which is intended to provide some helpful information about the page not existing. The template hierarchy for 404 pages is:
404.html
index.html
Embed hierarchy
The embed template is used when one site embeds a post from your WordPress site. WordPress wraps the output in an 
<iframe> and displays the embedded content according to the template.
Embed templates are not supported by the block templates system. To build and use custom embed templates, they must be located in your theme’s root folder and use the PHP file extension.
The template hierarchy for embedded content is:
embed-{post_type}-{post_format}.php
embed-{post_type}.php
embed.php
If a custom embed template is not included in the theme, WordPress will use the 
/wp-includes/theme-compat/embed.php template bundled with core. It does not fall back to the index template like other template types.
If you were embedding a post with a post type of 
post and the post format of 
image, the hierarchy becomes:
embed-post-image.php
embed-post.php
embed.php

Template Parts
Templates represent the top-level document structure for the front end of a website. But template parts represent smaller sections of content that can be included in one or more templates.
Some common parts are:
Header
Footer
Sidebar
Comments
You can have many more parts. These are generally pieces of the design that are reused within multiple top-level templates. Parts are not a requirement for your theme, but they are a nice-to-use feature that lets you better manage your files and code.
In Introduction to Templates, you learned about the basics of template parts. In this document, you’ll gain a deeper understanding of how they work.
How do template parts work?
As you learned in the Templates documentation, WordPress locates a top-level template based on which page a visitor is viewing on the website. This located template is then loaded, and WordPress parses the block markup before sending it back to the browser.
Unlike templates, parts are not automatically loaded based on the currently-viewed page. They must be included as a part of the top-level template via the Template Part block.
The Template Part block’s markup looks like this:
<!-- wp:template-part {"slug":"your-template-part-slug"} /-->
There are more block settings that you can include, but the 
slug property must be set to load the correct part. When WordPress encounters the Template Part block markup during its parsing process, it will look for a file named 
/parts/your-template-part-slug.html in your theme folder. If found, it will load the file and parse its block markup.
Let’s look at a simple template that loads both a Header and Footer part:
<!-- wp:template-part {"slug":"header","tagName":"header"} /-->
<!-- Other block markup goes here. -->
<!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->
As you can see, a 
tagName setting was also included for the Header and Footer parts. This sets the wrapping container elements to 
<header> and 
<footer>, respectively.
If this is the block markup included in a top-level template, WordPress would go through these steps:
Load the 
/parts/header.html file and parse its block markup.
Parse the template’s other block markup.
Load the 
/parts/footer.html file and parse its block markup.
What’s in a template part?
Template parts in block themes contain block markup and nothing else.
Let’s look at a simple Footer template part that shows a Site Title block and a Paragraph block with a “Powered by WordPress” message. To recreate this, you would add a 
/parts/footer.html file in your theme with this block markup:
<!-- wp:group {"align":"wide","layout":{"type":"flex","orientation":"vertical","justifyContent":"center"}} -->
<div class="wp-block-group alignwide">
	<!-- wp:site-title {"level":0} /-->
	<!-- wp:paragraph -->
		<p>Powered by WordPress.</p>
	<!-- /wp:paragraph -->
</div>
<!-- /wp:group -->
This is merely an example that shows block markup and how it could look in a part. Template parts can be even simpler or much more complex, depending on what you want to include in them.
For a more in-depth look at the architecture of a block, check out the Key Concepts documentation in the Block Editor Handbook.
Organizing template parts
With block themes, you must put template parts within your theme’s 
/parts folder. It should be structured like this:
parts/
comments.html
footer.html
header.html
sidebar.html
None of those are required. In fact, you don’t even have to include any template parts at all.
WordPress does not currently support nested template parts. For example, you cannot create a 
/parts/header folder and put multiple header parts within it. All template parts must be placed directly within your theme’s 
/parts folder.
Technically, WordPress will also look in the 
/block-template-parts folder if it exists in your theme. This is for backward compatibility with an older version of WordPress. But it is recommended to always use the 
/parts folder instead.
Building template parts
It’s possible to manually write the block markup code for all of your template parts. But, in most cases, you will want to work directly within the WordPress admin and its visual editor. Then, migrate the block markup from the editor to your template part files as described in Introduction to Templates.
To explore working with the visual interface, read the support guides on using the Site and Template Editors:
Template Part Block
Site Editor
Template Editor
How to edit templates via the Site Editor
How to use the Template Editor via the WordPress Block Editor
Registering template parts
While not required, you should almost always register template parts via 
theme.json. Doing so will ensure that they appear in the user interface for use with the Site and Template editors with nice labels that can be translated.
Registering template parts is covered in the Template Parts documentation under the Global Settings and Styles chapter.
Editing template parts
To access templates from the WordPress admin, open the Appearance > Editor menu in the admin menu. Then click the Patterns item in the sidebar and scroll to find the Template Parts section:
Template Parts are categorized by template part areas (read “Template part areas” section below for more information). Each area lists the parts that are registered for it (note that General is the 
uncategorized area).
The template parts shown can come from three locations:
User-created template parts saved in the database (these are stored as posts in the 
wp_template_part post type)
Template parts from the theme’s 
/parts folder
Template parts dynamically added by plugins
From this screen, you can make any customizations you want to the parts, adjusting them to fit your vision.
Remember that if you save the parts from this screen, they will be stored in the database and will overrule any templates in your theme. If you plan to distribute this theme to others or use it on another site, you must copy the block markup to the matching template in your 
/parts folder as described in Introduction to Templates.
Adding new template parts
You can create a new template by clicking the + icon next to Patterns heading. This will display a dropdown with several options. Click the Create template part option as shown here:
Then a popup modal will appear for you to enter a custom template part name and select its area:
By default, you can select from the General, Header, and Footer areas (to learn more about creating custom areas, read the “Template part areas” section below).
From the next screen, you will be able to create an entirely custom template part. It can include any blocks that you prefer.
Again, any new parts you add via the editor are saved in the database. You must create the template part file inside your 
/parts folder and copy the block markup to it if you intend to distribute your theme.
Template part areas
Template part areas are essentially a way to organize similar template parts. They also appear as navigational elements within the user interface. Below, you can see the Header area highlighted in the template-editing sidebar:
By default, WordPress has three areas that you can register your templates for:
uncategorized (labeled as General in the admin)
header
footer
That will cover some common use cases (almost all themes need a header and footer, for example). But you may want to create custom areas for your themes to better organize your template parts and provide a nicer user experience.
Registering custom areas
You can register as many custom areas you want by adding a filter to the 
default_wp_template_part_areas hook. Your callback function accepts a single parameter of 
$areas, which must be an array of area definitions. Each area definition must be an array with these key/value pairs defined:
area: The machine-readable slug for your template part area.
area_tag: The wrapping HTML tag to use for template parts assigned to this area. Can be one of the following:
div
article
aside
footer
header
main
section
label: A human-readable label for your area, which may be translated.
description: A description of your area and what template parts belong to it, which may be translated.
icon: The icon to use for the area. Note that only 
header, 
footer, and 
sidebar are currently supported with everything else falling back to a default icon, at least until this ticket is addressed.
Suppose you wanted to create an area named Loop to assign template parts used throughout your theme. You could do so by adding this code to your theme’s 
functions.php file:
add_filter( 'default_wp_template_part_areas', 'themeslug_template_part_areas' );
function themeslug_template_part_areas( array $areas ) {
	$areas[] = array(
		'area'        => 'loop',
		'area_tag'    => 'section',
		'label'       => __( 'Loop', 'themeslug' ),
		'description' => __( 'Custom description', 'themslug' ),
		'icon'        => 'layout'
	);
	return $areas;
}
This would register a new Loop area for your theme, but for it to be useful, you need to also register at least one template part for it as described in the 
theme.json documentation on registering template parts.
Suppose you also created a 
/parts/loop-default.html template part. You could assign it to your new 
loop area in 
theme.json with this code:
{
	"version": 2,
	"templateParts": [
		{
			"area": "loop",
			"name": "loop-default",
			"title": "Loop - Default"
		}
	]
}
This screenshot shows what the Loop area would look like in the Site Editor:
You can register as many template parts for an area as you need via 
theme.json. For example, you could register a 
loop-home.html and 
loop-author.html to use in your Home and Author templates, respectively. But these are mere examples. The only limit is your imagination.
There are many reasons you might want to register custom areas. For a deeper dive into the benefits and features of this system, read Upgrading the site-editing experience with custom template part areas from the WordPress Developer Blog.

Templates
Templates are one of the most important aspects of theme development. They are files that you put together to represent the document structure that appears on the front end of a website. When combined with Global Settings and Styles (
theme.json), you can ultimately create a unique design to use for yourself, clients, or just share with the world.
Templates are how you decide where things are placed within your theme.
Want a giant footer at the bottom of the site? You can do that by adding specific blocks inside a Group block at the bottom of a template.
Want a sidebar next to the content area? No problem. You can put a Columns block in one or more of your templates to create that layout.
In Introduction to Templates, you gained a broad overview of how the WordPress templating system works. In this document, we’ll dive more deeply into the templates themselves.
How do templates work?
Whenever someone visits any page on your site, WordPress takes a look at the URL, runs some logic under the hood, and figures out what type of page the visitor is looking at. That’s a very simplified explanation of it anyway. For theme development, you don’t need to know how this part of the process works too deeply—just what the end result is.
Once WordPress determines the type of page, it runs through its “template loader,” which searches for a template that matches the page type. It does this by attempting to locate templates within the template hierarchy for the page type, which is covered in detail in the Template Hierarchy documentation.
WordPress will search for templates in the hierarchy in order of priority. If it finds a match in any of these locations, it will stop searching through the hierarchy:
User-saved template in the database.
Template in a child theme’s 
/templates folder (if child theme is active).
Template in the theme’s 
/templates folder.
Once a template is found that matches the page type within the hierarchy, the template is loaded. Its block markup is then parsed and WordPress outputs the resulting HTML markup for the browser to use.
What’s in a template?
Block theme templates are composed entirely of block markup. That’s it. Really.
OK. It’s slightly more nuanced than that. You will generally see these things in block templates:
Block markup
References to template parts
References to block patterns
Ultimately, each of those things is still block markup.
Here’s a look at the 
/templates/404.html template file, which includes all three things:
<!-- wp:template-part {"slug":"header","tagName":"header"} /-->
<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
<main class="wp-block-group">
	<!-- wp:pattern {"slug":"twentytwentythree/hidden-404"} /-->
</main>
<!-- /wp:group -->
<!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->
Of course, block templates can be much more complex than that. The point is that block templates must consist entirely of block markup for WordPress to correctly parse the code and output it for the browser.
For a more in-depth look at the architecture of a block, check out the Key Concepts documentation in the Block Editor Handbook.
Organizing templates
With block themes, there is only one location that you can put block templates: in the theme’s 
/templates folder. It should be structured like this:
templates/
404.html
archive.html
author.html
home.html
index.html (required)
page.html
singular.html
The minimum required template file is 
index.html. The existence of this file is how WordPress determines that the theme is a block theme.
Outside of that, you can include as many or as few templates as you need to achieve your theme design.
Technically, WordPress will also look in the 
/block-templates folder if it exists in your theme. This is for backward compatibility with an older version of WordPress. But it is recommended to always use the 
/templates folder instead.
Building templates
While you can technically type all of the block markup for your templates in your template files, that is not what the typical experience will be when working with block themes. In most cases, you will be working from a visual interface and migrating your block code to your template files.
To explore working with the visual interface, read the support guides on using the Site and Template Editors:
Site Editor
Template Editor
How to edit templates via the Site Editor
How to use the Template Editor via the WordPress Block Editor
Editing templates
To access templates from the WordPress admin, open the Appearance > Editor menu in the admin menu. Then click the Templates item in the sidebar:
This screen lists all of the existing templates for the site, which can come from three locations:
User-created templates saved in the database
Templates from the theme’s 
/templates folder
Templates dynamically added by plugins
From there, you can make customizations to the existing templates, adjusting blocks to your liking.
Remember that if you save these, they will be stored in the database and will overrule any templates in your theme. If you plan to distribute this theme to others or use it on another site, you must copy the block markup to the matching template in your 
/templates folder as described in Introduction to Templates.
Adding new templates
You can create a new template by clicking the Add New Template (+ icon next to Templates heading). This will create a modal overlay as shown here:
From there, you will be able to create an entirely custom template (if it doesn’t already exist for editing).
Again, any new templates you add via the editor are saved in the database. You must create the template file inside your 
/templates folder and copy the block markup to it if you intend to distribute your theme. Be sure that your template filename matches a valid filename in the Template Hierarchy (for example, the Home template filename is 
home.html).
Custom templates
Custom templates are templates that you can assign to individual posts, pages, or entries of a custom post type. They are used for the single post view on the front end of the site.
You or your theme users can select custom templates from the Template setting in the Post/Page panel in the post editor sidebar:
This can be a powerful feature that lets you create unique designs for specific circumstances. For example, you could add something as simple as a different layout with a contact form or something as complex as a news-magazine layout with multiple post queries and other sections.
When adding a new template from the Templates screen, you can also create a custom template. From the Add Template overlay, there is an option named Custom Template. By clicking it, you will add a new custom template within your site’s database.
But to distribute your template with your theme, you must add it to a custom template file in your theme’s 
/templates folder.
The great thing about custom templates is that the filename can be anything you want it to be. Just be sure to avoid using the name of a standard template filename from the Template Hierarchy, so make sure it’s unique.
Because custom templates can be anything, there are no exact rules on what block markup should be included in them. But if you want to display the post or page content, make sure that you’re using the Post Content block somewhere within it.
The only other rule is that you must register your template via your 
theme.json file. How to do this is covered in the Custom Templates documentation under the Global Settings and Styles chapter.
Originally, custom templates were called “page templates.” This is because the feature only worked for pages in the initial implementation. Eventually, posts and other custom post types could use the feature, so it was rebranded to “custom templates.” But you may see these referred to as page templates in other documentation or on third-party sites.

Theme security issues
Please do not report security issues with WordPress Core to the themes team. To report an issue with WordPress itself, follow the directions for reporting security vulnerabilities.
If you have found a plugin with a security issue, please read Reporting Plugin Security Issues
How to report a theme
If you find a theme with a security issue, please do not post about it publicly anywhere. Even if there’s a report filed on one of the official security tracking sites, bringing more awareness to the security issue tends to increase people being hacked, and rarely speeds up the fixing.
To report a theme that is in the WordPress.org theme directory, please go to the theme’s directory listing (For example, https://wordpress.org/themes/twentytwentythree/) and use the “Report this theme” button in the sidebar, and complete the form.
You can also send reports of security issues to 
themes@wordpress.org. Include the following:
a clear and concise description of the issue
a link to the specific theme
whether or not you have validated the security issue yourself
optional – links to any public disclosures on 3rd party sites
For developers
What to do when you receive a request to update your theme
If your theme has been reported and the Themes Team decides that action needs to be taken, you will receive an email from the Themes Team with information and instructions.
– You may be asked to solve an issue within a specific time frame. This depends on the severity of the issue.
– The Themes Team may need to suspend your theme to prevent new downloads until the issue is resolved.
You must reply to the email if you have any questions, need more information, or need more time.
Test your theme update carefully and submit it through the upload form on the theme directory page.
Learn more about how the Themes team works with theme suspensions and delisting.
Resources
To learn more about theme security, please see the Security chapter of the common APIs handbook.
https://developer.wordpress.org/themes/theme-security/common-vulnerabilities
A Guide to Writing Secure Themes – Part 1: Introduction
A Guide to Writing Secure Themes – Part 2: Validation
A Guide to Writing Secure Themes – Part 3: Sanitization
A Guide to Writing Secure Themes – Part 4: Securing Post Meta