How to Create Your Own WordPress Theme from Scratch (2026)

Building your own WordPress theme is one of the most useful skills a developer can have. It gives you full control over how a site looks and behaves, removes the bloat of off-the-shelf themes, and makes you faster at every future project. The good news: the barrier to entry is lower than you think. A working theme needs just two files.

This guide covers everything from the bare minimum to a production-ready theme: what files you need, how the template hierarchy works, what to keep in mind, and concrete performance and security tips. Code examples are included throughout.

Note: WordPress now supports two theme types — classic (PHP templates) and block (HTML templates for Full Site Editing). This guide focuses on classic themes, which are still the best starting point for learning. Block themes are covered in the “What to keep in mind” section.

Laptop with code on screen for WordPress theme development

What is a WordPress theme?

A theme is a collection of files that determines how your WordPress site looks and how content is displayed. WordPress ships with a default theme (currently Twenty Twenty-Five). When you activate your own theme, WordPress swaps the templates but keeps your content, settings, and plugins intact.

A theme is not a plugin. Themes handle presentation (layout, design, typography). Plugins handle functionality (forms, SEO, caching). Keep that separation in mind — it will save you from building themes that break when deactivated.

The bare minimum: two files

WordPress recognizes a theme if it contains at least these two files in a folder under wp-content/themes/your-theme/:

style.css — must contain a theme header comment. This is how WordPress identifies the theme (name, author, version, etc.).
index.php — the fallback template. WordPress uses it when no more specific template exists.

style.css (the header)

/* Theme Name: My Theme Theme URI: https://example.com/my-theme Author: Your Name Author URI: https://example.com Description: A minimal WordPress theme built from scratch. Version: 1.0.0 License: GPL-2.0-or-later License URI: https://www.gnu.org/licenses/gpl-2.0.html Text Domain: my-theme */  /* Your CSS goes below */ body {   font-family: system-ui, -apple-system, sans-serif;   line-height: 1.6;   color: #1a1a1a;   max-width: 720px;   margin: 0 auto;   padding: 2rem 1rem; }

The header comment is mandatory. Without Theme Name, WordPress will not list the theme in the admin. Text Domain is used for translations (more on that later).

index.php (the fallback)

<?php /**  * The main template file.  *  * @package My_Theme  */  get_header();  if ( have_posts() ) :     while ( have_posts() ) :         the_post();         ?>         <article id="post-<?php the_ID(); ?>" <?php post_class(); ?>>             <h2><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h2>             <div class="entry-content"><?php the_excerpt(); ?></div>         </article>         <?php     endwhile;     the_posts_navigation(); else :     echo '<p>No posts found.</p>'; endif;  get_footer();

That is a complete, working theme. Upload the folder to wp-content/themes/, activate it in Appearance → Themes, and you have a live site. Ugly, but functional.

Building it out: the standard file set

A real theme splits responsibilities across files. Here is the file structure you will grow into:

my-theme/ ├── style.css          (required: theme header + styles) ├── index.php          (required: fallback template) ├── functions.php      (theme setup, enqueues, features) ├── header.php         (site header, <head>, opening markup) ├── footer.php         (closing markup, footer) ├── single.php         (single post) ├── page.php           (single page) ├── archive.php        (category, tag, date, author archives) ├── search.php         (search results) ├── 404.php            (not found) ├── comments.php       (comment form + list) ├── sidebar.php        (widget area) └── screenshot.png     (preview image in admin, 1200x900 recommended)

header.php

<?php /**  * The header for our theme.  */ ?> <!DOCTYPE html> <html <?php language_attributes(); ?>> <head>     <meta charset="<?php bloginfo( 'charset' ); ?>">     <meta name="viewport" content="width=device-width, initial-scale=1">     <?php wp_head(); ?> </head> <body <?php body_class(); ?>> <header class="site-header">     <h1><a href="<?php echo esc_url( home_url( '/' ) ); ?>"><?php bloginfo( 'name' ); ?></a></h1>     <p><?php bloginfo( 'description' ); ?></p>     <nav><?php wp_nav_menu( array( 'theme_location' => 'primary' ) ); ?></nav> </header> <main class="site-main">

footer.php

    </main>     <footer class="site-footer">         <p>&copy; <?php echo date( 'Y' ); ?> <?php bloginfo( 'name' ); ?></p>         <?php wp_footer(); ?>     </footer> </body> </html>

functions.php

<?php /**  * Theme functions and definitions.  */ function my_theme_setup() {     // Let WordPress handle the document title.     add_theme_support( 'title-tag' );      // Enable featured images.     add_theme_support( 'post-thumbnails' );      // Register a navigation menu.     register_nav_menus( array(         'primary' => esc_html__( 'Primary Menu', 'my-theme' ),     ) );      // Add support for HTML5 markup.     add_theme_support( 'html5', array( 'search-form', 'comment-form', 'comment-list', 'gallery', 'caption', 'style', 'script' ) );      // Add support for wide/full alignment in the block editor.     add_theme_support( 'align-wide' ); } add_action( 'after_setup_theme', 'my_theme_setup' );  function my_theme_scripts() {     // Main stylesheet.     wp_enqueue_style( 'my-theme-style', get_stylesheet_uri(), array(), wp_get_theme()->get( 'Version' ) );      // Main JavaScript (in footer).     wp_enqueue_script( 'my-theme-script', get_template_directory_uri() . '/js/main.js', array(), wp_get_theme()->get( 'Version' ), true ); } add_action( 'wp_enqueue_scripts', 'my_theme_scripts' );  // Register a widget area. function my_theme_widgets() {     register_sidebar( array(         'name'          => esc_html__( 'Sidebar', 'my-theme' ),         'id'            => 'sidebar-1',         'description'   => esc_html__( 'Add widgets here.', 'my-theme' ),         'before_widget' => '<section id="%1$s" class="widget %2$s">',         'after_widget'  => '</section>',         'before_title'  => '<h2 class="widget-title">',         'after_title'   => '</h2>',     ) ); } add_action( 'widgets_init', 'my_theme_widgets' );

Two rules here: never hardcode <link> or <script> tags in header.php — always use wp_enqueue_style() / wp_enqueue_script(). And always call wp_head() and wp_footer() — they are the hooks where WordPress injects core scripts, styles, and plugin output.

The template hierarchy (what to keep in mind)

WordPress decides which template file to load based on the URL. It looks for the most specific file first, then falls back to more generic ones. The final fallback is always index.php.

Single post: single-{post-type}-{slug}.php → single-{post-type}.php → single.php → singular.php → index.php
Single page: custom template → page-{slug}.php → page-{id}.php → page.php → singular.php → index.php
Archive: category-{slug}.php → category-{id}.php → category.php → archive.php → index.php
Home (blog): home.php → index.php
Front page: front-page.php → home.php → page.php → index.php
Search: search.php → index.php
404: 404.php → index.php

You do not need all of these. Start with index.php, single.php, page.php, and archive.php. Add more only when you need custom layouts for specific content types.

Classic vs block themes

Since WordPress 5.9, you can build block themes — themes whose templates are HTML files made of block markup, edited visually in the Site Editor (Full Site Editing). They use theme.json for global styles instead of CSS.

Classic themes (PHP templates) — what this guide teaches. Best for learning, full PHP control, works with all plugins.
Block themes (HTML templates + theme.json) — the future of WordPress. No PHP in templates, visual editing, but a steeper learning curve for dynamic logic.
Hybrid — a classic theme that adds theme.json for global styles and block support. A good middle ground.

If you are starting fresh in 2026, learn classic first, then migrate to block themes. The concepts (template hierarchy, the Loop, hooks) transfer directly.

What to keep in mind

Use child themes for modifications. Never edit a parent theme directly — updates will overwrite your changes. Create a child theme with just style.css (with Template: parent-theme-slug) and functions.php.
Prefix everything. Function names, CSS classes, option names, custom post types — prefix with your theme slug (e.g., mytheme_) to avoid collisions with plugins and other themes.
Use translation functions. Wrap all user-facing strings in esc_html__(), esc_attr__(), or _e() with your text domain. This makes your theme translatable.
Follow the coding standards. WordPress has official PHP, CSS, JS, and HTML coding standards. Use PHPCS with the WordPress ruleset to lint your code.
Test with real content. Import the Theme Unit Test data to check edge cases: long titles, no featured image, nested comments, sticky posts, pagination.
Support the block editor. Even classic themes should add add_theme_support( 'editor-styles' ) and enqueue an editor stylesheet so the backend matches the frontend.
Do not put functionality in themes. Custom post types, shortcodes, and metaboxes belong in plugins. Themes should be swappable without losing content.

Performance tips

Enqueue, never hardcode. Use wp_enqueue_style() and wp_enqueue_script() so WordPress can manage dependencies, minify, and conditionally load.
Load scripts in the footer. Pass true as the last argument to wp_enqueue_script() for non-critical JS. This improves First Contentful Paint.
Use wp_get_theme()->get('Version') as the version string. This busts the cache automatically when you update the theme.
Conditionally enqueue. Only load scripts/styles on pages that need them. Check is_single(), is_page(), etc. before enqueuing.
Minify and combine. Use a build tool (Vite, Webpack, or @wordpress/scripts) to minify CSS/JS and generate sourcemaps. WordPress 6.9 also inlines small block stylesheets automatically.
Optimize images. Use add_image_size() for custom sizes and serve WebP. Lazy-load images with loading="lazy" (WordPress adds this by default since 5.5).
Avoid render-blocking resources. Defer non-critical scripts. Inline critical CSS. Use font-display: swap for web fonts.
Limit HTTP requests. Combine small CSS/JS files. Use SVG sprites or icon fonts instead of multiple image files.
Cache aggressively. Rely on the host’s page cache (Nginx, Varnish) and object cache (Redis). Do not build your own caching in the theme.
Profile with Query Monitor. Install the Query Monitor plugin to find slow queries, hook callbacks, and enqueued assets on each page.

Security tips

Escape output. Use esc_html(), esc_attr(), esc_url(), esc_js() on every value you print. Never echo $variable; directly.
Sanitize input. Use sanitize_text_field(), sanitize_email(), sanitize_file_name(), absint() on all $_GET, $_POST, $_REQUEST values.
Validate data. Check types, ranges, and allowed values before using input. Use wp_verify_nonce() for form submissions.
Use nonces for forms. wp_nonce_field() in the form, wp_verify_nonce() on submission. Prevents CSRF.
Check capabilities. Use current_user_can( 'manage_options' ) (or the appropriate capability) before allowing admin actions.
Use $wpdb->prepare(). Never interpolate variables into SQL queries. Always use prepared statements.
Do not expose file paths. Use get_template_directory_uri() (URL) not get_template_directory() (path) in front-end output.
Disable file editing. Add define( 'DISALLOW_FILE_EDIT', true ); in wp-config.php so themes/plugins cannot be edited from the dashboard.
Keep dependencies updated. If you use third-party libraries, keep them current. Remove unused libraries.
Do not include jQuery from a CDN. Use the version bundled with WordPress to avoid version conflicts and security issues.
Set proper file permissions. Folders 755, files 644, wp-config.php 600/640.

Tools and workflow

Local environment: LocalWP, @wordpress/env, Docker, or XAMPP. Never develop on a live site.
Code editor: VS Code with the WordPress/PHP extensions, or PhpStorm.
Version control: Git. Commit often, use branches for features.
WP-CLI: scaffold themes with wp scaffold _s my-theme (Underscores starter). Inspect with wp theme list.
Testing: import Theme Unit Test data, test on mobile, test with screen readers, run Lighthouse.
Linting: PHPCS with WordPress ruleset, ESLint for JS, Stylelint for CSS.

Frequently asked questions

How long does it take to build a WordPress theme?
A minimal theme: a few hours. A production-ready theme with custom templates, responsive design, and accessibility: 1–4 weeks depending on complexity.

Do I need to know PHP?
Yes, for classic themes. You need basic PHP (loops, conditionals, functions) plus WordPress template tags. Block themes require HTML and theme.json but less PHP.

Should I use a starter theme?
For your first theme, yes. Underscores (_s) is the official starter. It gives you a clean, well-structured foundation without bloat. Once you understand the structure, you can start from scratch.

Can I sell my theme?
Yes. WordPress themes are GPL-licensed, so you can sell them. You can charge for support, updates, and premium features. ThemeForest and your own site are common marketplaces.

Classic or block theme — which should I learn first?
Classic. The concepts (template hierarchy, the Loop, hooks) are foundational and transfer to block themes. Block themes are the future, but classic is easier to debug and reason about.

Conclusion

Building a WordPress theme from scratch comes down to two files to start (style.css with a header, and index.php), then growing into the template hierarchy, functions.php, and the standard template files. Keep presentation in the theme and functionality in plugins, escape everything you output, enqueue assets properly, and test with real content.

Start small: get index.php and style.css working, then add header.php, footer.php, and functions.php. Add templates one at a time as you need them. The WordPress Theme Handbook and the Theme Unit Test data are your best companions. Happy theming.