Template Parts in Block Themes
A template part is a reusable chunk of a block theme, most often the header or footer, that multiple templates pull in. It replaces header.php and footer.php, and it edits like the rest of the site editor rather than like PHP.
What a template part is: a chunk of a block theme, saved as its own set of blocks, that one or more full templates pull in by reference. Header and footer are the two you will meet first, and they do the job header.php and footer.php did in a classic theme, but as editable block markup instead of PHP includes.
Part, pattern, template — the difference that trips people up
These three look similar in the site editor because all three are made of blocks, and the confusion is understandable.
- A template controls a type of page — the single post template, the archive template, the 404 template. It lays out the whole document.
- A template part is a piece a template includes, most commonly the header and footer, but a theme can define others: a sidebar, a page-title band, a comments section.
- A pattern is a block arrangement you insert into content. Once inserted, it belongs to that piece of content. Editing the pattern's own definition afterwards does not touch pages that already used it.
The distinction that matters in practice: editing a template part changes every template that references it, in one move. Editing an inserted pattern changes only the one place you inserted it. If you want a change to appear everywhere the header shows up, you want a template part.
Where a template part lives
A block theme ships default template parts as .html files under a parts directory, each holding the block markup and a small comment header naming its slug and title. Until you touch one in the site editor, the part you see there is read straight from that file.
The moment you make an edit and save it, WordPress writes a customised copy to the database as a wp_template_part post, keyed to the theme and the part's slug. From then on, that database row is what renders, and the theme's file becomes the fallback nobody is reading. This is the same file-then-database pattern that WordPress block themes use everywhere in the site editor, not something specific to parts — it is also how theme.json relates to global styles, which override it in the database.
Two consequences follow directly:
- A theme update leaves your edits alone. The update replaces the theme's files; your customisation sits in the database and is never touched.
- Switching themes drops the customisation. The new theme has no row keyed to its own slug, so it falls back to whatever
partsfile it ships, and your edited header is gone from view — though the old row is not deleted, it is just no longer referenced.
Clear customisations
Open a template part in the site editor and, when it carries database edits, an options menu offers a command along the lines of "Clear customisations." Running it deletes the wp_template_part row and reverts the part to whatever the theme file defines. There is no in-between state to inspect first — it is a full revert, not a per-block undo, so treat it the way you would treat discarding uncommitted changes.
If you only need to undo the last few edits, use the editor's regular undo instead; save the reverted state to keep it. Clear customisations is for "throw away everything I changed here and start from the theme's version."
Creating a new part
From the site editor's template parts listing (or the block inserter, while editing a template), add a new one, name it, and pick an area: Header, Footer, or General/Uncategorized. The area is metadata, not enforcement — WordPress does not stop you assigning header content to a part marked General — but it drives how the editor and some patterns treat the part, so match it to what the part actually is.
A freshly created part is empty. Build it with ordinary blocks — Group, Navigation, Site Title, Social Icons, whatever the design needs — the same blocks used anywhere else, including the widgets many of them replaced. To use it, insert it into a template through the block inserter's Template Parts tab, or reference it from a new template you are building. A part with nothing referencing it just sits unused; it is not automatically applied anywhere.
Assigning a different part per template
Because a template only references a part by slug, swapping which part a template uses is how you get, say, a stripped-down header on a landing page. Open the landing-page template, select the existing header part, and replace it with a different one from the inserter. The change only affects templates you explicitly repoint — everything else keeps using the original.
| Question | Answer |
|---|---|
| Edit the header once, does it change every page? | Yes, if every template references the same part |
| Does a theme update erase my header edit? | No |
| Does switching themes keep my header edit? | No, the new theme's own part shows instead |
| Does Clear customisations touch other parts? | No, only the one you run it on |
When to reach for a template part versus a pattern
Use a part for anything structural that should stay identical across the site: header, footer, a global CTA band that appears on every archive. Use a pattern for a layout an editor drops into individual posts or pages and might then adjust locally — a pricing table, a testimonial block, a hero section that varies page to page, closer in spirit to what a page builder produces. Confusing the two is the most common source of "I changed it in one place and it changed everywhere" or the opposite complaint, "I changed it and nothing happened."
Common mistakes
- Editing the theme's part file directly, expecting the site editor to reflect it. Once a customised database row exists, the file is ignored until that row is cleared.
- Assuming a theme update will fix a broken header. It won't touch your customisation at all — the fix is Clear customisations or a manual edit.
- Forgetting a customisation exists after switching themes back. Switch back to the original theme and the old edited header reappears, which surprises people who thought it was gone for good.
- Leaving the area set to General for an actual header or footer. Some theme patterns and editor affordances key off the area, so an unassigned part can behave oddly in the inserter.
- Not saving after Clear customisations. The revert happens in the editor session; leaving without saving can leave things in an unexpected state.
Verify
Open the site editor, edit the header template part, save, and confirm the change appears on the front end across a couple of different page types — a post and a page, not just the one you were viewing. Then check a template that should not be affected, to confirm parts scope correctly. If you are testing theme-switch behaviour, switch themes, view the front end, then switch back and confirm your original edit reappears rather than having been deleted.
Frequently asked
- No. A pattern is a starting point you insert and then own as part of the content it lands in. A template part is referenced by the templates that use it, so one edit updates every page that includes it.
- It did not. A theme update only replaces the theme's own files, and an edited template part is stored in the database, not in those files, so it is left alone. What actually resets it is switching to a different theme or using Clear customisations.
- Yes. Create a second template part, assign it the header area, and reference it from whichever templates should use it instead of the default. A landing-page template is a common reason to do this.