Blog
Content Fragments vs. Experience Fragments: when to use each.
In short. Use Content Fragments when what you reuse is the content itself: structured, design-free data shown on several channels or delivered to an app through an API. Use Experience Fragments when what you reuse is an assembled experience: a group of components with their layout that looks the same on many pages, such as a header, a footer or a promotion. The deciding question is whether the design travels with the content or each channel supplies its own.
What is the real difference between them?
Both exist so you do not repeat content, which is why teams mix them up. They solve different problems, though:
- A Content Fragment is content without presentation. It follows a model with typed fields (text, date, number, references to other fragments) and lives in Assets, under /content/dam.
- An Experience Fragment is content with presentation. It is built from components on an editable template, just like a page, and lives under /content/experience-fragments.
- Each channel shapes a Content Fragment its own way: the site through a component, a mobile app through its own UI. An Experience Fragment is designed once by the author and looks the same wherever it is placed.
When is a Content Fragment the right choice?
When the same content has to reach more than one place and each place presents it differently. Typical cases:
- Headless delivery: a mobile app, a SPA or a site outside AEM reads the content through the AEM GraphQL API, using persisted queries the CDN can cache.
- Content with a stable structure: product details, people profiles, FAQs, locations or legal notices.
- Content you need to query and filter: listings by date, category or any field in the model.
- Variations of the same text (a short and a long version, for example) without duplicating the fragment.
When is an Experience Fragment the right choice?
When what repeats is a whole section, layout included, and authors want to edit it in one place:
- Headers and footers shared across the whole site, or across several sites.
- Banners, promotions and call-to-action blocks that appear on many pages.
- Personalization offers: an Experience Fragment can be exported to Adobe Target as an offer.
- Channels that accept ready-made HTML: the plain HTML rendition (the .plain.html selector) makes it available to other systems.
- Variations of the same block per channel or context, such as a web version and an email version.
Can you combine them?
Yes, and it is often the best option. An Experience Fragment can contain a Content Fragment component: the layout stays in the Experience Fragment and the data in the Content Fragment. A promotion is assembled once, while the price, the dates or the legal copy are updated in their Content Fragment and also reach the app that consumes them through the API.
Which modeling mistakes should you avoid?
These are the patterns we look for when we review an inherited AEM project, because they are expensive to undo once real content is in place:
- Using Experience Fragments as a data source for another channel, which then has to scrape the content out of HTML.
- Storing design inside a Content Fragment: rich text fields with tables, columns or styles that only make sense on a page.
- Generic models with a title and a free-form body that ignore typed fields and cannot be filtered.
- Chains of fragment references that go too deep and make both queries and editing harder.
- One Experience Fragment per page: if it is not reused, it is just another component and belongs on the page.
- Not deciding up front how each kind of fragment gets translated: language copies and the translation workflow differ between the two.
What happens to the cache when you publish a fragment?
This is what catches teams off guard in production. When a page includes an Experience Fragment or a Content Fragment, AEM resolves it while rendering the page, so the HTML cached by the Dispatcher and the CDN already contains it. Publishing the fragment does not, by itself, invalidate the pages that use it.
Decide at design time how those pages get invalidated: through the Dispatcher invalidation setup, with cache lifetimes that match how often the fragment changes or, for headers and footers, by loading them separately. For headless delivery, review the cache headers of your persisted queries instead.
The questions we use to decide
Before creating the first model or template, we answer these:
- Is this content shown on more than one channel, or only on site pages?
- Does the author decide the layout once, or does each channel present it differently?
- Do we need to query or filter it by its fields?
- Who edits it, and how often does it change?
- How is it translated, and how is the cache invalidated when it changes?
The short version
If the design travels with the content, it is an Experience Fragment; if each channel brings its own, it is a Content Fragment; if you need both, combine them. If your AEM project already has fragments nobody dares to touch, reviewing the content model before a migration or a redesign saves you from rebuilding it twice.