Components let you define reusable groups of fields once and use them across models and content entries. They help reduce duplication and keep content structures consistent across your schema.

#Key terms

• Component: A predefined set of fields that can be reused across models and content entries. Think of a component as a flexible template where you define the fields once, and then fill them with different content each time you use it in an entry.

• Component instance: A specific occurrence of a component, with content, inside a content entry. The Studio UI supports linking up to 50 component instances, for both basic and modular component fields, to a single entry. Instances beyond the first 50 are still queryable through the API, but they won’t be visible in the Studio UI. This limit is intentional, as referencing a large number of component instances can significantly slow down queries and increase the risk of errors.

• Component field: A field type in your Hygraph schema that allows you to use components in a model. Component fields can be basic or modular. Both types can be configured to allow multiple values. If multiple values are allowed, the field can contain multiple component instances in a content entry.

  • Basic component field: Allows only one component type.
  • Modular component field: Allows two or more component types.

• Nested components: Lets you add component fields within a component, such as a parent component containing one or more child components.

#Benefits of using components

With components, you can:

• Reuse structured field groups across models
• Reduce schema duplication
• Keep complex content models easier to manage and scale

This saves time and improves the content editing experience.

#Components or references

Components and references (relations) both support reuse, but they reuse different things:

• Components reuse a structure (a set of fields). Each component instance stores its own content inside the entry.
• References reuse existing content entries from another model.

Example: You want to attach authors to a blog post.

• With references, you create author entries in an Author model, then link those entries to posts. This works well when a defined set of authors contributes across many posts.
• With components, you don’t need separate author entries. Instead, you add an author component instance to each post and fill in the fields each time. This works well when many different people can be authors and you don’t want to maintain author profiles as separate entries.

For more guidance, see Components or references.

#Add a component to your model

The process of adding a component to your model involves two steps:

1. Create a component.
2. Add the component to your model using a component field.

#Create a component

Creating a component

1. Navigate to the Schema Builder.
2. In the left sidebar, find the Components section below your models and click + Add.
3. Enter a name for your component in Display name. The system autocompletes API ID and Plural API ID, but you can edit them if needed.
4. Click Create component.
5. Your component is empty initially. You can add different fields to it. For example, you might create an Address component with single-line text fields for address lines and city, and a number field for ZIP code.

#Add a component field to your model

Adding a component field to a model

1. Navigate to the Schema Builder, then open the model you want to add a component field to.
2. From the Field types sidebar, select one of the component fields:
   • Basic: Allows a single component.
   • Modular: Allows two or more components.
3. Enter a name for your component field in Display name. The system autocompletes the API ID and Plural API ID, but you can edit them if needed. Optionally, add a Description.
4. You can configure the component field to Allow multiple values.
5. For a Basic component field, use Select component to choose a single component. For a Modular component field, use Select allowed components to choose multiple components.
6. On the Validations tab, you can choose to make the component field required.
7. On the Advanced tab, you can enable conditional visibility for the component field so that the component only displays in the content form when needed. This simplifies the way the content form displays when the schema contains deeply nested structures. Learn how to set it up here.
8. Click Add.

#Use a component in a content entry

After adding a component to your model, open the Content Editor to test it. The video above shows four common configurations:

• Basic component field that does not allow multiple values
• Basic component field that allows multiple values
• Modular component field that does not allow multiple values
• Modular component field that allows multiple values

In general, component fields work as follows:

1. In the Content Editor, open the model you configured and click + Add entry.
2. Find your component field in the entry form.
3. If it’s a basic component field, click + Add component. If it’s a modular component field, select a component from the dropdown. This creates a component instance.
4. Add content to the component instance.
5. If the field allows multiple component instances, you can:
   • Duplicate an existing instance using the context menu and selecting Duplicate. This creates a new instance of the existing component and copies its content.
   • Click + Add another component, or Add component below / Add component above from the context menu.
6. You can remove and reorder component instances using the context menu or the arrow controls. The Remove all option removes all instances at once.

#Nested components

Nested components let you add component fields to a component, so you can reuse structured sections within other sections.

For example, you can create a Section component and a Subsection component, then nest the subsection inside the section.

How to use nested components

1. Open a component that you've created.
2. From the Field types sidebar, add either a Basic or Modular component field to the component you want to nest into.
3. Enter the component field Display name. The system autocompletes the API ID and Plural API ID, but you can edit them if needed. Optionally, add a Description.
4. Select the component you wish to nest into the current one from the Select component dropdown for a Basic component field, or the Select allowed components dropdown for a Modular component field.
   • When you add a component field, components that your previously created are displayed. Ensure that you have created all the components you need before performing this step.
5. Click Add.

The nested component field appears in the parent component’s field list.

#Use nested components in an entry

After creating a nested component at the schema level, create a new entry and add the nested component as a subsection inside the component you added it to.

Add nested components

#Related docs

• API reference for components - API reference document on fetching components.
• Components or references - Guidance on when to use components vs. references.