How to Create a WordPress Theme from Scratch with Underscores

Introduction

Creating a custom WordPress theme from zero is an empowering way to learn the WordPress ecosystem and deliver precise functionality and styles for your clients or personal projects.
Underscores (often called _s) is a widely recommended starter theme developed by the WordPress team that provides a clean, minimal foundation without prebuilt styling.
In this guide, youll go step-by-step from environment setup all the way to packaging your theme for distribution.

Prerequisites

• Basic knowledge of HTML, CSS, PHP, and JavaScript.
• Local development environment: WordPress installed (using MAMP, XAMPP, Local, etc.).
• Code editor of your choice (VS Code, PhpStorm, Sublime Text).
• FTP/SFTP client if you plan to upload to a remote server.

1. Understanding Underscores

Underscores is not a full-fledged theme its a starter. It contains:

• A minimal style.css with proper theme headers
• Core template files: index.php, header.php, footer.php, etc.
• Predefined template tags and WordPress best practices
• A basic functions.php preparing theme support and asset enqueueing

Get the latest version at underscores.me. Enter your custom theme name, and download a ZIP file.

2. Theme Installation and Directory Structure

1. Unzip the downloaded package.
2. Rename the folder to your theme slug (e.g., my-theme).
3. Place it inside wp-content/themes/.
4. Activate via Appearance rarr Themes in your WordPress dashboard.

Key Files and Folders

3. Configuring Your Theme

3.1 style.css

At the top of style.css, youll find the theme header. Customize details:

/
Theme Name: My Theme
Theme URI: https://example.com/my-theme
Author: Your Name
Author URI: https://example.com
Description: A custom theme built with Underscores.
Version: 1.0
License: GNU General Public License v2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html
Text Domain: my-theme
/
    

3.2 functions.php

Use functions.php to:

• Enqueue styles and scripts via wp_enqueue_style and wp_enqueue_script.
• Add theme support for features (add_theme_support(post-thumbnails), add_theme_support(custom-logo)).
• Register navigation menus (register_nav_menus()).
• Include modular files (require get_template_directory() . /inc/customizer.php).

4. Building Core Templates

WordPress follows a template hierarchy. Customize templates for various contexts:

• header.php, footer.php: Site wrapper markup.
• index.php: Fallback loop for posts/pages.
• single.php: Single post layout.
• page.php: Static page layout.
• archive.php, category.php, tag.php: Listing archives.
• search.php: Search results.
• 404.php: Not-found page.

4.1 The Loop

if ( have_posts() ) :
  while ( have_posts() ) : the_post()
    get_template_part( template-parts/content, get_post_format() )
  endwhile
  the_posts_navigation()
else :
  get_template_part( template-parts/content, none )
endif
    

5. Adding Customizer Support

The WordPress Customizer provides real-time preview of theme modifications. In functions.php or an included inc/customizer.php, hook into customize_register:

function mytheme_customize_register( wp_customize ) {
  wp_customize->add_section( colors , array(
    title    => __( Header Colors, my-theme ),
    priority => 30,
  ) )
  wp_customize->add_setting( header_textcolor , array(
    default   => #000000,
    transport => refresh,
  ) )
  wp_customize->add_control( new WP_Customize_Color_Control( wp_customize, header_textcolor, array(
    label    => __( Header Text Color, my-theme ),
    section  => colors,
    settings => header_textcolor,
  ) ) )
}
add_action( customize_register, mytheme_customize_register )
    

6. Responsive Design and Assets

• Use a mobile-first CSS approach with media queries in style.css:

@media (min-width: 768px) {
  .site-header { display: flex justify-content: space-between }
}
    

• Enqueue third-party libraries or compile assets via build tools (webpack, Gulp). Example in functions.php:

  wp_enqueue_script( mytheme-main, get_template_directory_uri() . /assets/js/main.min.js, array(jquery), 1.0, true )
  wp_enqueue_style(  mytheme-style, get_stylesheet_uri(), array(), 1.0 )
          

7. Internationalization (i18n)

Prepare your theme for translation by using __() and _e() functions:

lth2gtltphp _e( Welcome to My Theme, my-theme ) gtlt/h2gt
    

Load text domain in functions.php:

function mytheme_setup(){
  load_theme_textdomain( my-theme, get_template_directory() . /languages )
}
add_action( after_setup_theme, mytheme_setup )
    

8. Adding a Theme Screenshot

Include screenshot.png (1200×900px) in the theme root. This image will represent your theme in the dashboard.

9. Testing and Validation

• Use the Theme Check plugin to ensure coding standards compliance.
• Validate HTML/CSS with W3C tools (HTML Validator, CSS Validator).
• Test responsive breakpoints on real devices or with browser dev tools.
• Audit performance with PageSpeed Insights.

10. Packaging and Distribution

1. Remove development comments and unused assets.
2. Increment version number in style.css and package.json if applicable.
3. Zip the theme folder.
4. Submit to the WordPress Theme Directory or share privately with clients.

Conclusion

Building a theme with Underscores streamlines the initial setup so you can focus on design and functionality. By following established WordPress best practices, leveraging the Customizer API, and ensuring internationalization and responsiveness, your custom theme will be robust, performant, and ready for users worldwide.

For comprehensive documentation on WordPress theme development, visit the official Theme Handbook.