Building WordPress Custom Themes From The Ground Up

Key points:

• Modern WordPress theme development encompasses classic PHP themes, hybrid approaches, and block-based full-site editing.
• WordPress relies on a structured template hierarchy to determine content display, enabling granular control through templates.
• Advanced Custom Fields (ACF®) enhances themes by enabling custom fields, modular blocks, and flexible content layouts, improving both functionality and user experience without complex coding.
• Best practices include modular file structures, performance optimization, and accessibility, ensuring lightweight, maintainable, and high-performing themes for diverse needs.

WordPress theme development has changed. What started as a PHP template system has splintered into three paths: classic themes using template files and hooks, full-site editing powered by the block editor, and hybrid approaches blending PHP with blocks.

We’re taking you from core template hierarchy principles to advanced techniques like template parts and block-based integration. We’ll cover:

• How to build custom themes from the ground up.
• Extending functionality with tools like Advanced Custom Fields (ACF®), or fully embracing the built-in toolset.
• Structuring content, implementing custom fields, and optimizing development workflows for scalable, maintainable themes without stumbling through outdated documentation.

Understanding custom WordPress theme development: Core concepts and workflow

WordPress themes come in three flavors:

• Classic themes rely on PHP templates and WordPress’s robust hooks and filters, giving developers full control over layout and functionality.
• Block themes are designed for the Full-Site Editor (FSE), using the Gutenberg block editor for a more visual, drag-and-drop approach.
• Hybrid themes sit between these two, combining the flexibility of classic PHP-based themes with modern block-based tools.

If you’re building a custom theme, chances are you want the best of both worlds – control and ease of use. That’s why this guide focuses on hybrid themes. Blending PHP templates with block editor compatibility allows for structured content while leaving space for tools like ACF Blocks to extend functionality.

At the heart of WordPress theme development is the template hierarchy, a cascading system that determines which PHP file is responsible for rendering specific content.

When a page loads, WordPress first looks for the most specific template – say, single-product.php for eCommerce products – before falling back to broader templates like single.php, and ultimately, index.php. This structure allows for granular control over content presentation while ensuring default templates catch any missing customizations.

The hierarchy integrates with WordPress core functions and hooks. Take category archives as an example: WordPress first checks for category-slug.php, then category-id.php, and if neither exists, it defaults to archive.php or index.php.

This progressive fallback system makes it possible to fine-tune templates for specific taxonomies, post types, or custom content without breaking site-wide consistency.

A typical WordPress theme consists of key template files: index.php (required), header.php, footer.php, and specialized files like single.php for posts and page.php for static pages. These templates interact with functions.php, which registers theme features, enqueues assets, and extends functionality.

Modern development refines this approach with block themes, using theme.json for global styles and settings. Tools like ACF Blocks tap into this to provide a structured way to integrate custom fields into the block editor, enabling dynamic content management while keeping development flexible and scalable.

How to develop a custom WordPress theme

Now, let’s get into building a classic PHP-based theme from scratch, structuring templates and enqueuing assets. Then, we’ll evolve it into a hybrid theme and incorporate advanced functionality with ACF.

1. Setting up

Before writing a single line of code, set up a structured development environment.

Start by installing Local – a local WordPress development tool that lets you create a sandboxed WordPress instance without external hosting dependencies.

Next, define your theme’s structure with design mockups. Focus on content layout, navigation patterns, and block placements rather than just aesthetics. Whether you use Figma or a hand-sketched wireframe, you need this as the blueprint for your template hierarchy and styling.

A few more tools that’ll make your work easier here include:

• A code editor with PHP and WordPress support, such as PhpStorm or VS Code with WordPress-specific extensions.
• Version control with Git to track changes and collaborate efficiently.
• Browser-based developer tools, available in Chrome or Firefox, for debugging CSS, JavaScript, and performance issues.

2. Creating theme files

Create the files that structure your WordPress theme. Add the following files to /wp-content/themes/your-theme/:

• style.css defines theme metadata (name, author, version) and holds your main styles.
• index.php acts as the fallback template for all pages if no other specific template exists.
• singular.php handles single posts and pages, offering more control over individual content.
• archive.php manages category, tag, and date-based archives.
• header.php, footer.php, and sidebar.php provide template parts for reusable sections across pages.
• functions.php powers your theme by adding features like menus, scripts, and custom functionality.

3. Adding basic theme functionality

Now that your theme files are set up, it’s time to enable key WordPress features. This involves defining navigation menus, widget areas, theme support options, and asset management:

1. In functions.php, use register_nav_menus() to define custom menus and register_sidebar() for widget zones:

function mytheme_setup() {
    register_nav_menus([
        'primary' => __('Primary Menu', 'mytheme'),
        'footer'  => __('Footer Menu', 'mytheme'),
    ]);

    register_sidebar([
        'name'          => __('Sidebar', 'mytheme'),
        'id'            => 'sidebar-1',
        'before_widget' => '<div class="widget">',
        'after_widget'  => '</div>',
    ]);
}
add_action('after_setup_theme', 'mytheme_setup');

2. Enable essential features like post thumbnails, custom logos, and title tags:

add_theme_support('post-thumbnails');
add_theme_support('title-tag');
add_theme_support('custom-logo');

3. Properly enqueue CSS and JavaScript in functions.php:

function mytheme_assets() {
    wp_enqueue_style('theme-style', get_stylesheet_uri());
    wp_enqueue_script('theme-scripts', get_template_directory_uri() . '/assets/js/main.js', [], false, true);
}
add_action('wp_enqueue_scripts', 'mytheme_assets');

4. Use get_header() and get_footer() in index.php to load global elements from header.php and footer.php.
5. Use a loop in index.php to display posts dynamically:

if (have_posts()) {
    while (have_posts()) {
        the_post();
        the_title('<h2>', '</h2>');
        the_content();
    }
} else {
    echo '<p>No posts found.</p>';
}

4. Converting it into a hybrid theme

At this point, you have a classic theme that’s ready to go. As promised, though, we’re going to convert it into a hybrid theme so we can take advantage of modern WordPress features:

1. Create the theme’s files in its directory:
   • hybrid-functions.php to handle block-related scripts and styles.
   • /assets/js/editor-enhancements.js to add block variations and editor tweaks.
   • /assets/css/editor-styles.css to define custom block editor styles.
   • theme.json to control global styles and settings for block themes.
2. In hybrid-functions.php, enqueue JavaScript for block variations:

function load_hybrid_theme_scripts() {
    wp_enqueue_script(
        'hybrid-editor-js',
        get_template_directory_uri() . '/assets/js/editor-enhancements.js',
        array('wp-blocks', 'wp-dom-ready', 'wp-edit-post'),
        null,
        true
    );
}
add_action('enqueue_block_editor_assets', 'load_hybrid_theme_scripts');

3. Load CSS for the block editor and frontend:

function load_hybrid_theme_styles() {
    wp_enqueue_style(
        'hybrid-editor-css',
        get_template_directory_uri() . '/assets/css/editor-styles.css',
        array(),
        filemtime(get_template_directory() . '/assets/css/editor-styles.css')
    );
}
add_action('enqueue_block_assets', 'load_hybrid_theme_styles');

4. Define global styles in theme.json:

{
  "version": 3,
  "settings": {
    "layout": {
    "contentSize": "800px",
    "wideSize": "1200px"
    },
    "color": {
    "palette": [
        { "slug": "accent", "color": "#ff5722", "name": "Accent Color" },
        { "slug": "background", "color": "#f4f4f4", "name": "Background" }
    ]
    },
    "typography": {
    "fontSizes": [
        { "name": "Small", "slug": "small", "size": "14px" },
        { "name": "Large", "slug": "large", "size": "24px" }
    ]
    }
  }
}

5. Enable block features in hybrid-functions.php:

function hybrid_theme_supports() {
    add_theme_support('editor-styles');
    add_theme_support('responsive-embeds');
    add_theme_support('disable-custom-font-sizes');
    add_theme_support('disable-custom-colors');
}
add_action('after_setup_theme', 'hybrid_theme_supports');

6. Create a block-based template structure. Make two directories: /templates/ to hold the index.html  and single.html, and /parts/ to store reusable blocks like header.html and footer.html. Here’s a sample of what you can add to the index.html file, which you’ll need to make this work:

<!-- wp:template-part {"slug":"header"} /-->
<!-- wp:post-content /-->
<!-- wp:template-part {"slug":"footer"} /-->

With this setup, your theme supports both classic and block-based features, making it compatible with the Gutenberg Editor while allowing more advanced functionality like custom block creation via ACF Blocks. Speaking of which…

5. Adding advanced theme functionality

You can combine ACF, custom theme settings, and specialized templates to make your WordPress theme more flexible and powerful. These features allow for structured content, modular design, and easy customization without overwhelming users with complexity.

Custom ACF Blocks are a great way to create reusable content sections within the block editor. Use acf_register_block_type() to define unique blocks tailored to your site’s needs. This is useful for elements like testimonials, pricing tables, or call-to-action sections, ensuring they follow a consistent design and structure.

For more control over content input, ACF’s custom field groups let you assign specific fields to post types or templates. This makes it easy for users to enter structured data, such as team member details, portfolio items, or product specifications. You can set these up directly in the ACF interface without coding.

To improve site-wide customization, use the WordPress Customizer by adding options through the customize_register hook. This lets you adjust settings like colors, fonts, and logos directly from the WordPress dashboard, making branding changes quick and easy.

Finally, use WordPress’s template hierarchy to create specialized layouts for different content types. Custom templates for categories, post types, or landing pages help deliver a more tailored experience.

6. Installing the theme

Once your theme is complete, it’s time to move it from LocalWP to a live WordPress site. Follow these steps to ensure a smooth transition:

1. In LocalWP, go to wp-content/themes/your-theme/ and compress it into a zip file.
2. Go to your site’s dashboard, then Appearance > Themes > Add New.
3. Click on Upload Theme to display the file selector, hit Browse… and choose the relevant zip file, then click Install Now.
4. When you get the success message that the theme has been installed, click on Live Preview to open the Site Editor and ensure everything looks right.
5. After testing everything you can and being satisfied, click Activate & Publish.

Best practices for creating a custom WordPress theme

A solid WordPress theme requires a development approach that won’t make you regret your decision six months from now. Here are some best practices you should follow to build one:

• Use separate tools to extend functionality without bloating the theme. For example, ACF Blocks lets you add structured content without cluttering the theme with hardcoded solutions. This keeps everything flexible and future-proof.
• Organize files in a modular structure for better maintainability. Break the theme into clear directories like partials/ for reusable sections, components/ for independent UI elements, and assets/ for styles and scripts. Use get_template_part() to pull in these sections, keeping your main template files tidy and easy to navigate.
• Use the Customize API instead of hardcoding settings. Use the customize_register hook to define settings, sections, and controls in the WordPress Customizer. This allows users to tweak theme options dynamically without editing code. Apply these settings in templates with get_theme_mod(), ensuring flexibility and a better user experience.
• Standardize code to keep projects maintainable. Use a formatter like Prettier to enforce consistency, write clear, well-documented functions, and avoid unnecessary complexity.
• Optimize for performance and efficiency to avoid turning the theme into a bottleneck. Minify CSS and JavaScript files to reduce load times. Implement lazy loading for images using native HTML attributes or plugins like Autoptimize. Limit database queries in templates by caching results where possible and avoiding expensive calls in loops.
• Ensure accessibility so the theme works for all users. Use semantic HTML to improve navigation and readability. Include ARIA roles where necessary, but don’t overuse them. Maintain high color contrast and test for screen reader compatibility with tools like Axe or WAVE.

Make your custom WordPress theme stand out with ACF

As you’ve seen, a great custom WordPress theme is built on structure, performance, and scalability – starting with a clean template hierarchy. Keep logic separate from presentation, optimize assets, and follow best practices for security, accessibility, and speed.

But to make your theme truly stand out, opt for ACF. It enables dynamic, modular functionality without bloating your code. Use ACF Blocks for flexible content and unlock ACF PRO’s other premium features for repeatable fields, media galleries, and advanced customization.

Not to mention, with extensive documentation and a thriving developer community, ACF gives you the tools to push WordPress further than ever.

So, if you’re serious about building smarter, more scalable themes, it’s time to explore ACF PRO and start pushing the limits of WordPress.