Easily restore your project to a previous version with our new Instant One-click Backup Recovery
Hygraph
Classic Docs
You are currently reading the Classic Docs. If you were looking for the Studio Docs check here

Components or references

#Overview

This document discusses components & references. We'll dive into the use of each while providing some ideas on deciding whether to use one or the other depending on what you're trying to achieve and how to combine them.

#Definitions

ComponentsComponents

A component is a predefined set of fields that can be reused across models and content entries. Think of a component as a flexible, reusable template where you define the fields once - in the Schema - and then fill them with different content every time you use the component in a content entry.

ReferencesReferences

References are relations between two or more content entries in your project. With references, you can reuse content entries by connecting them. Once the relation is configured, you can also use it to create related content from the content creation screen.

#How to choose

The definitions above hint at an overlap in what you could achieve using one or the other, especially when reusing content.

For instance, you can achieve similar results by adding a component field to a model than by relating two models through a reference field. In both cases, you will add certain data to an entry for the front end to use afterward.

In some cases, you could use one or the other, depending on how you want to design your project. Let's look into some of the different aspects we should consider when deciding which one to use:

#Repeated content

Components make sense for content structure reutilization. Using them for a block of fields reused across different models saves time, as developers working on the Schema don't have to recreate the same structure repeatedly.

Relations can serve the purpose of reusing content. The main difference here would be that while the component needs to be filled with new data every time, the relation would require you to set up the related model & create the entries first.

The choice here depends on project characteristics. Let's use an example of an Author component. Authors can be attached to a content entry using either components or relations.

In the case of relations, you need to create your Authors first - in a separate model - and then reuse these content entries by attaching them to a post using the relation field. This works well if you have a small team of authors, each with their own Author profile.

In the case of components, you don't have to create Author entries before creating a Blog post content entry. However, every time you add an Author component instance to your post, you will need to fill in all of the fields from scratch. This works well if many different users can be the Authors of your content entries, and creating an Author profile for each doesn't make sense.

#Simplified content creation screen

Using components in content entries declutters the screen, whether they are intended only to be included if needed or if they are meant to allow a user to select one of many components. This improves the Editor experience because seeing the whole content entry on one screen allows them to navigate it easily.

A good example of this is the modular component field. You can use this field to create a dynamic content creation screen for your Editors, where one single model can result in very different entries depending on which components are selected from the modular component field.

They also ensure content entries have the minimum required information you want as you could, for instance, make a modular component containing product types, each containing a set of fields marked as required. Those fields will only be required if the component is selected from the modular component field, guaranteeing that the minimum required information is provided for all entries before publishing, irrespective of the product type for which the entry is being created. With this feature, you can achieve this for different product types with a single model.

An alternative to this, which we often see, is that rather than using components, projects use relations that connect to other models, which act as a form to add certain information. As if the related model were a component without being one, and by creating & adding a relation in the content creation screen, your Editors fill in that data in the relation overlay. Here, developers will create the related model once, which will be used many times to add new information - similar to what you can achieve with components. The result is more models and what could potentially be a less friendly experience for Editors, which we will get into in a moment.

#Editor work

References make sense for linking existing information; for this use case, they are better than components. However - as we mentioned above - they also allow users to create new related content entries from the content editor screen itself by opening an overlay, so it's essential to make a distinction here when it comes to how your Editors will be working:

If the expectation is that Editors will use relations as links to connect to existing entries, then the flow becomes smooth and easy for them. Components wouldn't make sense in a case like this, so it's a lot easier to choose the feature that best fits your project.

If, however, the expectation is for Editors to edit the related content or create new related entries, it might be complicated for them to grasp how relations work. For instance, if you have books connected to an author, you're in the book content entry, and want to create & add a new author through it, the editing flow may not be friendly enough for Editors who are more used to more editor-focused CMSs. In that case, components might be preferable.

Another issue that stems from using relations for a use case like this is that Editors may not understand what other parts of the project content can be impacted when editing related content, depending on the reference type.

An exception to this would be projects where components get too big. There, components may crowd the content editing screen too much, making it hard to navigate and may present some performance issues. In cases where components get too large and introduce a standalone piece of information - again, like a book connected to an author, for instance, but with many fields - it might be better to use relations because your Editors might find it easier to have that whole section as an overlay in one piece.

In conclusion, relations are better if something already exists and you want to add a link. If you're creating content from scratch, then components are better - unless it would result in a really large component, in which case a relation would be the best choice again, for the sole reason that you'd be completing that large set of fields in an overlay.

#Content duplication

The need for content duplication can also be a decisive point when using relations or components. If Editors work on a project where content duplication is expected, keep in mind that only specific types of relations get duplicated along with the content.

The system will only duplicate two-way references with cardinality many-to-many and many-to-one in relations where more than one model can be referenced, and two-way references with cardinality many-to-many where only one model can be referenced.

This document contains a complete list showing whether relations are duplicated depending on their characteristics.

#Conclusion

Relations work best if:

  • Something already exists, and you want to add a link.
  • Content is reused, unchanged, in several places - i.e. a set of related entries in a blog.
  • A lot of related content needs to be added from scratch, but would result in a really big component.

Components work best if:

  • Your project uses repeated content structures — for instance, a block of fields that gets reused across many models.
  • Content is being created from scratch every time the structure is reused.
  • You want to have a simplified and dynamic content creation screen for your Editors.
  • Content creation for your project relies heavily on content duplication.

#Combine them

Components and relations can be combined in cases where you want a structure of fields to remain the same but also offer the possibility to relate to other already existing content entries.

You could, for instance, create a simple component that contains a title, a slug, and relations; you could use it in different models to add related products, new arrivals, other products of the same vendor, other books of the same author, etc.

#Example use cases

  • Relations: E-commerce project that contains Categories and Product as separate models, where categories can hold products and products can belong to more than one category. The two entities can be connected through a two-way reference field.
  • Components: E-commerce project where different product types are sold. Having all fields for all possible products listed on the edit screen crowds it too much, making navigation harder, and has the added disadvantage that those fields cannot be made required because, naturally, not all products have all that information. Besides the fields all products may have in common - i.e. a name and description field - which can live at the model level, different product types need to have certain required fields to guarantee that published entries contain sufficient information. A way to do this while also simplifying your screen is to have a Product model, where you add the common fields, as well as a “product type” modular component field containing two basic component fields - i.e. one for clothes and one for accessories - each with its own set of required fields. The fields related to a product type are revealed when selected and only become required then.