Components and references can both be used to reuse and structure content, but they serve different purposes. This guide explains the key differences, when to choose one over the other, and when to combine them.
#Definitions
Components
A component is a predefined set of fields reusable across models and content entries. You define the fields once in the schema, then fill them with different content each time the component is used in an entry.
References
A reference is a relation between two or more content entries in your project. References let you reuse existing entries by connecting them. Once a relation is configured, editors can also create related content directly from the content editor.
#How to choose
Because both features support content reuse, the right choice depends on how your content is structured and how your editors work. The sections below cover the main factors to consider.
#Repeated content
Use components when you want to reuse a field structure across multiple models. Defining the structure once as a component saves developers from recreating the same fields repeatedly. Each time the component is used in an entry, editors fill it in from scratch.
Use references when you want to reuse existing content entries rather than a field structure. You set up the related model and create the entries first, then link them to other entries using a reference field.
Example: Attaching authors to blog posts
- With references, create author entries in a dedicated
Author model, then link them to posts. This works well when you have a known set of authors, each with their own profile.
- With components, add an author component instance directly to each post and fill in the fields each time. This works well when many different people can be authors and maintaining individual author profiles isn't practical.
#Simplified content creation screen
Components help keep the content creation screen focused and easier to navigate. Instead of displaying all fields at once, a modular component field lets editors select only the component types relevant to the entry they're creating. This results in a more dynamic and streamlined editing experience.
Components also support conditional required fields. For example, a modular component containing different product types can mark certain fields as required only when that product type is selected. This guarantees minimum required information is captured for every entry without cluttering the screen with irrelevant fields.
References can produce a similar result when a related model acts as a structured form. Editors fill in the data through an overlay when creating or linking a related entry. However, this approach typically results in more models and can be a less intuitive experience for editors unfamiliar with how relations work.
#Editor experience
References work best for linking to existing content. The flow is straightforward. Editors search for and attach an existing entry. Components are not a good fit for this use case.
However, if editors are expected to create new related entries rather than just link to existing ones, references can become confusing. For example, creating a new author from inside a book entry, through a relation overlay, may not feel intuitive to editors accustomed to more traditional CMS interfaces. In that scenario, components are often the better choice.
Exception: when a component becomes very large, it can crowd the content editing screen and introduce performance issues. If the content in question is a substantial, standalone piece of information, such as a detailed author profile with many fields, a reference may be preferable, since editors can complete that larger form in an overlay rather than inline.
In summary:
- Use references when linking to something that already exists.
- Use components when creating content from scratch, unless the component would be very large, in which case a reference with an overlay may provide a better editing experience.
#Content duplication
If your project relies on content duplication, note that not all relation types are duplicated when an entry is copied. Only the following are duplicated:
- Two-way references with many-to-many or many-to-one cardinality, where more than one model can be referenced.
- Two-way references with many-to-many cardinality, where only one model can be referenced.
Components are always duplicated with their parent entry.
For a complete breakdown, see Duplicating content.
#Conclusion
Use components when:
- Your project reuses the same field structure across multiple models.
- Content is created from scratch each time the structure is reused.
- You want a simplified, dynamic content creation screen for editors.
- Your project relies on content duplication.
Use references when:
- You want to link to content that already exists.
- Content is reused unchanged across multiple entries. For example, a shared set of related posts in a blog.
- The related content is large enough that completing it in an overlay is preferable to filling it in inline.
#Combining components and references
Components and references are not mutually exclusive. You can use them together when you need a consistent field structure that also links to existing content entries.
For example, you could create a component containing a title, a slug, and a reference field. Reused across different models, this component could link to related products, new arrivals, products from the same vendor, or books by the same author, while keeping the structure consistent.
#Example use cases
Components: An e-commerce project that sells multiple product types. Listing all possible product fields on a single edit screen makes it hard to navigate, and those fields cannot be made required universally since not all products share the same attributes. A better approach is a Product model with common fields, such as name and description at the model level, and a modular component field for product type. Each component (for example, one for clothing and one for accessories) defines its own set of required fields. Those fields appear only when the relevant product type is selected, keeping the screen clean and ensuring that all published entries include the minimum required information.
References: An e-commerce project with Category and Product as separate models, where a product can belong to more than one category. The two models are connected through a two-way reference field, letting editors link products to categories without duplicating data.