WordPress locate_template Example: Resolve Theme Files Cleanly

Last reviewed: May 16, 2026

Theme code and theme-aware plugins sometimes need to resolve a template file dynamically without hardcoding a single path. locate_template() is the core helper for that job. It checks the child theme and parent theme in the right order and returns the first matching template path, which is exactly what override-aware code needs.

This guide shows how to use locate_template() cleanly, why it is safer than guessed filesystem paths, and where developers should stop short of loading arbitrary user-controlled filenames.

Resolve a known template from an explicit allowlist

<?php
$template = locate_template(
	array(
		'partials/content-security-card.php',
		'partials/content-default-card.php',
	),
	false,
	false
);

if ( $template ) {
	include $template;
}

This keeps template resolution override-aware while still limiting the possible files to a controlled set. That is the right balance for production theme code.

Do not feed raw request values into template resolution

locate_template() is a filesystem helper, not a routing sandbox. If the filename originates from request input, it should be mapped through an explicit allowlist first. Production code should decide which templates exist instead of letting outside input steer file inclusion directly.

Keep the load step separate when you want clearer control flow

The helper can load the template for you, but many teams prefer returning the path first and including it explicitly. That makes conditional fallbacks, logging, and debugging easier to read during reviews.

Common mistakes

• Guessing child-theme and parent-theme paths manually. The helper already handles override order.
• Letting request input choose the template file directly. Always map through a controlled set.
• Assuming the path always exists. Check the return value before including it.
• Mixing filesystem resolution with rendering decisions in one opaque branch. Keep the flow explicit.

Production checklist

• Use locate_template() when child-theme override order matters.
• Pass an explicit list of acceptable template candidates.
• Check the returned path before including it.
• Keep request-driven template choice behind an allowlist.
• Review theme-aware plugin code for hardcoded template paths.

Related reading

Pair this with the get_template_part guide for reusable theme fragments and with the template hierarchy article when the broader WordPress loading order drives which template should exist at all.

References and further reading

• WordPress Code Reference: locate_template()
• WordPress Code Reference: get_template_part()
• WordPress Theme Handbook: Template Hierarchy