th:insert vs th:replace for Modular UI Component Wrapping

When building modular UI components in a Spring Boot application using Thymeleaf 3.0+, the choice of fragment inclusion method directly impacts the final DOM structure. The primary goal is to maintain a clean HTML hierarchy while ensuring that essential CSS layout constraints are preserved.

Using th:insert preserves the host element, which is useful when the parent container provides necessary IDs or CSS classes for grid and flexbox layouts. Conversely, th:replace removes the host element entirely, reducing DOM depth and preventing redundant wrapper <div> tags when the fragment already includes its own structural container.

The uncertainty arises when components must be reused across different page layouts where some require the host wrapper for styling and others require a flat structure for performance or semantic reasons.

• Which attribute is more sustainable for a design system where fragment containers are standardized?
• In what scenarios does th:replace risk breaking CSS selector targeting compared to th:insert?