Referencing parent-theme blocks

When customizing a theme, blocks from a parent theme (e.g., Hyva/default) are often modified or moved.

A common mistake is copying a parent theme's block declaration to make adjustments. While this might seem to work initially, it can lead to unexpected issues.

TLDR; use referenceBlock in child themes

In short: When customizing existing parent theme blocks in a child theme, always use <referenceBlock name="example"> instead of <block name="example">.

Background

To understand why, it's helpful to know how Magento generates pages.
Magento processes layout instructions from the lowest priority fallback theme up to the current, highest priority theme.

When Magento encounters a <block> tag, it registers the block using its name, arguments, and parent reference for instantiation. If it finds another <block> tag with the same name, it discards the existing block record and replaces it entirely with the new one.

In contrast, a <referenceBlock> tag updates the existing block record instead of replacing it.

What can using block instead of referenceBlock cause?

Copying <block> declarations into a child theme complicates upgrades.
If the parent theme adds or changes block arguments, your copied block in the child theme will mask these updates.
This can introduce subtle, hard-to-debug issues.

Using <referenceBlock> ensures that any new block arguments or changes in updated parent themes apply automatically.