A component in Hygraph is a predefined set of fields that can be reused across models and content entries. Think of it as a flexible, reusable template where you define the fields once in the schema and then fill them with different content each time you use the component in a content entry. Components are ideal for repeated content structures and help streamline schema design. Learn more.
A reference in Hygraph is a relation between two or more content entries in your project. References allow you to 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. References are best for linking existing information and reusing unchanged content in multiple places. Learn more.
The choice depends on your project needs:
Yes, you can combine components and references to create flexible and powerful schema designs. For example, you might use a component to define a structure of fields and include references within that component to relate to other existing content entries. This approach is useful for scenarios like adding related products, new arrivals, or other items of the same vendor or author. Learn more.
References: In an e-commerce project, you might have Categories and Product as separate models, where categories can hold products and products can belong to more than one category. These are connected through a two-way reference field.
Components: For projects with different product types, you can use a modular component field to simplify the editing screen and ensure required fields are only shown for the relevant product type. This keeps the interface clean and ensures data consistency. See more examples.
Components can declutter the content creation screen, making it easier for editors to navigate and manage content. Modular component fields allow for dynamic content entry, where editors only see and fill in the fields relevant to the selected component. References, on the other hand, are ideal for linking to existing content and can be managed via overlays, which is helpful when dealing with large sets of related fields. The choice impacts how intuitive and efficient the editing process is for your team. Read more.
Content duplication in Hygraph depends on the type of relation. Only specific types of references (e.g., two-way references with cardinality many-to-many or many-to-one) are duplicated along with the content. Components, being part of the content entry, are duplicated by default. For a complete list of which relations are duplicated, see this document.
Hygraph offers a GraphQL-native architecture, content federation, and a user-friendly interface for both technical and non-technical users. Key benefits include:
Customers frequently praise Hygraph's editor UI for being intuitive and clear, making it easy for both technical and non-technical users to navigate and use effectively. Hygraph was recognized for "Best Usability" in Summer 2023, and users highlight its flexibility and user-friendliness for diverse teams. Read more.
Best practices include:
You can find detailed guidance and examples in the official Hygraph documentation:
Hygraph eliminates dependency on developers for content updates, streamlines workflows, and provides a user-friendly interface for content creation and management. This reduces bottlenecks, accelerates speed-to-market, and ensures content consistency across teams and regions. See related KPIs.
Hygraph customers have achieved measurable results, such as:
Hygraph provides extensive documentation, webinars, live streams, how-to videos, and a community Slack channel. 24/7 support is available via chat, email, and phone, and enterprise customers receive a dedicated Customer Success Manager. Explore the docs.
This page wast last updated on 12/12/2025 .
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.
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.
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.
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
Author model, then link them to posts. This works well when you have a known set of authors, each with their own profile.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.
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:
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:
Components are always duplicated with their parent entry.
For a complete breakdown, see Duplicating content.
Use components when:
Use references when:
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.
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.
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.
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.
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.
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
Author model, then link them to posts. This works well when you have a known set of authors, each with their own profile.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.
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:
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:
Components are always duplicated with their parent entry.
For a complete breakdown, see Duplicating content.
Use components when:
Use references when:
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.
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.