References in Hygraph are relations between two or more content entries, allowing you to connect items such as an Author to a Blog Post or a Category to a Product. You can configure references to define the type, direction, and cardinality of the relationship. Note: Changing reference type, model to reference, direction, or cardinality is not possible after creation. Learn more in the documentation.
Hygraph supports four types of reference relationships: one-to-one, one-to-many, many-to-many, and many-to-one. Each type determines how content entries can be linked. For example, one-to-one is suitable for linking a country to its capital, while many-to-many can link products to multiple categories and vice versa. Note: The available options depend on the direction (one-way or two-way) you select during configuration.
To configure a reference field, you select the reference type (single or multiple models), direction (one-way or two-way), and cardinality (one-to-one, one-to-many, etc.). You can also set display names, API IDs, descriptions, conditional visibility, and field visibility (read/write, read-only, hidden, or API only). For two-way references, you must also configure the reverse field. Note: Once created, reference type, direction, and cardinality cannot be changed.
After creating a reference field, you cannot change its type, the model to reference, direction, or cardinality. Only the models available in a union filter can be edited after the initial save. Relational field types behave differently when content is duplicated. Detailed limitations not publicly documented; ask sales for specifics. See duplicating content documentation.
You can sort related content by opening the content entry containing the references, finding the reference field, and using the drag-and-drop handle to reorder the relations. This allows you to control the display order of linked entries. Note: Sorting is only available for reference fields that support multiple entries.
Conditional visibility allows you to display a reference field in the content form only when certain conditions are met. This is configured in the reference field's settings. For more details, see the conditional fields documentation. Note: Conditional visibility is optional and may not be suitable for all use cases.
Whether to use a reference or a component depends on your content model needs. References are best for linking distinct content entries, while components are suitable for reusable content structures within a single entry. For guidance, see this documentation. Note: The choice impacts how content is managed and queried.
Hygraph offers flexible reference configuration (one-to-one, one-to-many, many-to-many, many-to-one), conditional visibility, drag-and-drop sorting, and granular field visibility (read/write, read-only, hidden, API only). These features support complex content models and workflows. Note: Some advanced features may require careful planning to avoid schema limitations after creation.
Yes, Hygraph provides a GraphQL Content API and a Management API for programmatic access to content and schema, including references. The Asset Upload API and MCP Server API are also available for asset management and AI assistant integration. For details, see the API Reference documentation. Note: API-only fields are not visible in the UI and can only be managed via API.
Comprehensive technical documentation is available at hygraph.com/docs/developer-guides/schema/references. Additional guides cover schema components, conditional fields, duplicating content, and API usage. Note: Documentation for Hygraph Classic is available separately for legacy projects.
Support resources include extensive documentation, onboarding guides, community Slack, webinars, and live training. Starter projects and technical kickoffs are available for new users. For help, visit Hygraph Documentation or join the community at slack.hygraph.com. Note: Some advanced support may require a paid plan.
Common use cases include linking authors to blog posts, products to categories, products to order items, and products to reviews. References enable complex content relationships for scenarios such as eCommerce catalogs, editorial workflows, and multi-language content. Note: Overly complex reference structures may impact performance or manageability; plan your schema accordingly.
Hygraph's reference system allows you to model complex relationships (e.g., many-to-many between products and categories) and control visibility, sorting, and access. This supports advanced content architectures for global teams and multi-channel delivery. Note: Schema changes to references are restricted after creation, so plan carefully.
Before creating references, carefully plan your schema, as reference type, direction, and cardinality cannot be changed after creation. Test your setup to avoid issues, and consult documentation on duplicating content and conditional fields. Note: Poor planning may require schema redesign or data migration later.
Best practices include planning your content model in advance, using descriptive display names and API IDs, leveraging conditional visibility for dynamic forms, and testing reference behavior with sample data. Review documentation for edge cases such as duplicating content and managing reverse fields. Note: Overuse of references can complicate content management; use them judiciously.
This page wast last updated on 12/12/2025 .
References are relations between two or more content entries that you can create in Hygraph. You can configure them in different ways.
This document gets into the schema configuration of the different types.
You can use references to connect content entries to one another.
Examples of this could be linking an Author to a Blog Post, or a Category to a Product.
When you add a reference to your schema, you will need to configure its type, direction and cardinality. Four types of references can result from this configuration.
References - Define relationship
Define relationship
Reference type: Use the radio buttons to select whether the field will be able to reference one model, or more.
Model to reference: Use the dropdown to select one or more models, depending on your previous selection.
Reference directions: Use the radio buttons to define if content will be queryable from one side or both.
In the case of one-way references, the reference will only be seen in one model in the UI. The referenced model will not have a reference field and users won't be able to see the connected entries.
Reference cardinality: Use the dropdown to define whether it will be possible to connect one or many entries to the parent entry, as well as the directions of that relation.
Changing reference type, model to reference as well as reference direction and relation cardinality isn't possible after creating the reference field.
In the case of union filters specifically, you will be able to edit the models available in the relation after the initial save.
Relational field types behave differently from one another when content is duplicated. Check out our document on Duplicating content to learn more about this.
Please carefully plan and test your setup before creating any content to avoid issues.
Scroll down to move onto the next step.
References - Configure reference
Read / Write is selected by default.
At this point of the configuration process you will have different options depending on the direction you selected. If you are creating a one-way reference, you can finalize the process here by clicking on Add. If you are creating a two-way reference, you need to scroll down to configure the reverse field:
References - Configure reverse field
Define relationship section. You can change the configuration, or continue as is.
Read / Write is selected by default.
Finally, click Add to save the reference.
One-to-one references let you add a relation to a content entry from the model or models configured as referenceable. A referenceable model is one you link during field configuration.
Editors using the content form will be able to link to only one other entry from the selected model, as an exclusive relation between two entries.
A great example to show this type of relation is a country and its capital. Each country has one capital, and each capital belongs to only one country.
The following video shows an example of how to set up a one-to-one reference:
One-to-many references let you add references to multiple content entries from the model or models configured as referenceable. A referenceable model is one you link during field configuration.
Editors using the content form will be able to link to multiple content entries from the selected model or models.
A great example to show this type of relation is a schema where you have a product model and an order item model, in which you can relate one product to many order items.
The following video shows an example of how to set up a one-to-many reference:
Another example of this type of reference could be an author that is related to many blog posts.
Many-to-many references let you add references to multiple content entries from the model or models that you link to during configuration, while also allowing content entries from the other model or models to link to several content entries from this one.
A great example to show this type of relation is a schema where you have a product model and a category model, in which one product can be related to multiple categories, and one category can be related to multiple products.
The following video shows an example of how to set up a many-to-many reference:
Many-to-one references let you add a reference to one content entry from the model or models that you link to during configuration, while allowing entries from the referenced model or models to link to multiple entries from this one.
A great example to show this type of relation is a schema where you have a product model and a reviews model, in which one product can be related to multiple reviews, but a review can be related to only one product.
The following video shows an example of how to set up a many-to-one reference:
Another example of this could be a number of blog posts related to a single author.
If you have doubts whether you should use a reference or a component, check out our document on this subject.
You can use the Conditional visibility option in a reference field so that the reference only displays in the content form when needed.
You can find the Conditional visibility checkbox in the Configure section of your reference configuration screen:
Conditional references
Check out this document to learn how to set up conditional visibility.
References are relations between two or more content entries that you can create in Hygraph. You can configure them in different ways.
This document gets into the schema configuration of the different types.
You can use references to connect content entries to one another.
Examples of this could be linking an Author to a Blog Post, or a Category to a Product.
When you add a reference to your schema, you will need to configure its type, direction and cardinality. Four types of references can result from this configuration.
References - Define relationship
Define relationship
Reference type: Use the radio buttons to select whether the field will be able to reference one model, or more.
Model to reference: Use the dropdown to select one or more models, depending on your previous selection.
Reference directions: Use the radio buttons to define if content will be queryable from one side or both.
In the case of one-way references, the reference will only be seen in one model in the UI. The referenced model will not have a reference field and users won't be able to see the connected entries.
Reference cardinality: Use the dropdown to define whether it will be possible to connect one or many entries to the parent entry, as well as the directions of that relation.
Changing reference type, model to reference as well as reference direction and relation cardinality isn't possible after creating the reference field.
In the case of union filters specifically, you will be able to edit the models available in the relation after the initial save.
Relational field types behave differently from one another when content is duplicated. Check out our document on Duplicating content to learn more about this.
Please carefully plan and test your setup before creating any content to avoid issues.
Scroll down to move onto the next step.
References - Configure reference
Read / Write is selected by default.
At this point of the configuration process you will have different options depending on the direction you selected. If you are creating a one-way reference, you can finalize the process here by clicking on Add. If you are creating a two-way reference, you need to scroll down to configure the reverse field:
References - Configure reverse field
Define relationship section. You can change the configuration, or continue as is.
Read / Write is selected by default.
Finally, click Add to save the reference.
One-to-one references let you add a relation to a content entry from the model or models configured as referenceable. A referenceable model is one you link during field configuration.
Editors using the content form will be able to link to only one other entry from the selected model, as an exclusive relation between two entries.
A great example to show this type of relation is a country and its capital. Each country has one capital, and each capital belongs to only one country.
The following video shows an example of how to set up a one-to-one reference:
One-to-many references let you add references to multiple content entries from the model or models configured as referenceable. A referenceable model is one you link during field configuration.
Editors using the content form will be able to link to multiple content entries from the selected model or models.
A great example to show this type of relation is a schema where you have a product model and an order item model, in which you can relate one product to many order items.
The following video shows an example of how to set up a one-to-many reference:
Another example of this type of reference could be an author that is related to many blog posts.
Many-to-many references let you add references to multiple content entries from the model or models that you link to during configuration, while also allowing content entries from the other model or models to link to several content entries from this one.
A great example to show this type of relation is a schema where you have a product model and a category model, in which one product can be related to multiple categories, and one category can be related to multiple products.
The following video shows an example of how to set up a many-to-many reference:
Many-to-one references let you add a reference to one content entry from the model or models that you link to during configuration, while allowing entries from the referenced model or models to link to multiple entries from this one.
A great example to show this type of relation is a schema where you have a product model and a reviews model, in which one product can be related to multiple reviews, but a review can be related to only one product.
The following video shows an example of how to set up a many-to-one reference:
Another example of this could be a number of blog posts related to a single author.
If you have doubts whether you should use a reference or a component, check out our document on this subject.
You can use the Conditional visibility option in a reference field so that the reference only displays in the content form when needed.
You can find the Conditional visibility checkbox in the Configure section of your reference configuration screen:
Conditional references
Check out this document to learn how to set up conditional visibility.