- Article
- 3 minutes read
- Reviewed August 3, 2026
The WordPress template hierarchy determines which template renders a requested page. Custom post types and taxonomies participate in the same query-based selection system as built-in content.
Understanding the hierarchy separates content registration from presentation and allows themes to provide specific designs with reliable fallbacks.
The Template Loader
WordPress identifies the main query type, creates a list of candidate templates and loads the first available match.
Classic themes use PHP template files. Block themes use HTML block templates and may also use templates customized by users and stored in the database.
Single Custom Post Type Templates
A single Event entry can use a type-specific template such as single-event.php in a classic theme or single-event.html in a block theme.
More specific templates can target an individual entry before falling back to the type-level, generic single, singular and index templates.
Post Type Archive Templates
When a type has a public archive, WordPress looks for an archive template specific to the post type and then broader archive fallbacks.
An archive template should be designed around the structured fields and visitor tasks of the collection, not merely a generic chronological list.
Taxonomy Term Templates
Custom taxonomy archives can use templates specific to the taxonomy or an individual term. Generic taxonomy, archive and index templates provide fallbacks.
Categories and tags have their own related branches of the hierarchy.
Classic Theme Examples
single-event.phpfor individual events.archive-event.phpfor the event archive.taxonomy-event_type.phpfor all Event Type terms.taxonomy-event_type-conference.phpfor one Conference term.
Block Theme Templates
Block themes package templates in a /templates directory and use block markup. User customizations can override packaged templates through records in the database.
When debugging a block theme, check both theme files and user-created template customizations.
Custom Fields in Templates
Templates should retrieve metadata through stable APIs, handle missing values and escape output for its context.
Do not assume every older record contains every newly added field. Design useful fallbacks and migration processes.
Query Loops and Archives
Archive templates use the main WordPress query by default. Replacing it with unrelated custom queries can break pagination, canonical behaviour and integrations.
Modify the main query carefully when filters or ordering are required, and preserve the query semantics of the archive.
Theme Independence
A post type should not require one theme merely to remain accessible. Its plugin can provide fallback rendering or document theme requirements, but the data definition should remain separate.
Themes should avoid registering business-critical content types whose records disappear from the interface when the design changes.
Template Testing Matrix
- Single entry with complete and missing fields.
- Post type archive and pagination.
- Taxonomy terms with many, one and zero results.
- Search results and 404 behaviour.
- Private or restricted content.
- Classic and block theme expectations where supported.
- User-customized block templates.
Frequently Asked Questions
Does a custom post type require a custom template?
No. WordPress can fall back to generic single, archive or index templates, although a specific template often provides a better design.
Why is my block theme ignoring a template file change?
A user-customized template stored in the database may override the theme file. Check the Site Editor and template reset options.
Should a plugin register a post type and its template?
A plugin should own the content type. It may provide fallback display, while the theme can offer a design-specific template.