# Components

Learn how to create and use reusable components in Hygraph to model content faster, reduce duplication, and keep schemas maintainable.

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

| Term                  | Description |
| --------------------- | ----------- |
| **Component**         | A predefined set of fields reusable across models and entries. It is like a flexible template where you define the fields once, then fill them with different content each time the component is used in an entry. |
| **Component instance** | A specific occurrence of a component with its own content inside a content entry. |
| **Component field**   | A field type in your Hygraph schema that lets you embed components within a model. Can be **basic** or **modular**, and both types support multiple values. |
| **Basic component field** | Allows only one component type. |
| **Modular component field** | Allows two or more component types. |
| **Nested components** | A component that contains one or more child component fields, enabling hierarchical content structures. |

**Note:**

**Studio UI limit:** The Studio UI supports linking up to **50 component instances** per entry (for both basic and modular fields). Instances beyond 50 remain fully queryable via the API, but won't appear in the UI. This limit exists because a large number of component instances can slow down queries and increase error risk.

## Why use components

Components are useful when you need to:

- Reuse the same group of fields across multiple models without redefining them
- Reduce schema duplication and maintenance overhead
- Keep complex content models easier to manage as they scale

This saves time and improves the content editing experience.

## Components vs. references

Both components and references support reuse, but they serve different purposes:

- **Components** reuse a field structure. Each component instance stores its own unique content within the entry.
- **References** reuse existing content entries from another model.

**Example: Attaching authors to blog posts**

| Approach | How it works | Best for |
|--------- |------------- |--------- |
| **References** | Create entries in an `Author` model and link them to posts. | A fixed set of known authors who contribute to many posts. |
| **Components** | Add an author component instance directly to each post and fill in the fields. | Variable or one-off authors where maintaining separate author profiles isn't needed. |

For more detailed guidance, see [Components or references](https://hygraph.com/docs/developer-guides/schema/components-or-references).

## Add a component to your model

Adding a component involves two steps:

1. [Create a component](#create-a-component).
2. [Add a component field to your model](#add-a-component-field-to-your-model).

**Note:**

Components currently do not support remote sources or Rich Text embedding.

### Create a component

[Video: Creating a component in the Schema Builder](https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9xayvhu9b07vx89uwd88w)

1. Open the **Schema Builder**.
2. In the left sidebar, locate the **Components** section below your models and click **+ Add**.
3. Enter a name in the **Display name** field. The **API ID** and **Plural API ID** fields are auto-populated, but you can edit them.
4. Click **Create component**.
5. Your new component is empty. Add [fields](https://hygraph.com/docs/api-reference/schema/field-types) to define its structure.

**Example:** An `Address` component might include single-line text fields for address lines and city, and a number field for ZIP code.

**Note:**

The number of components you can create depends on your Hygraph plan. See [pricing details](https://hygraph.com/pricing).

### Add a component field to your model

[Video: Adding a component field to a model in the Schema Builder](https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9xa50hu7207vx78msiw7j)

1. Open the **Schema Builder** and select the model you want to update.
2. From the **Field types** sidebar, select a component field type:
   - **Basic**: embeds a single component type.
   - **Modular**: embeds two or more component types.
3. Enter a **Display name**. The **API ID** and **Plural API ID** are auto-populated but editable. Optionally, add a **Description**.
4. Toggle **Allow multiple values** if the field should accept more than one component instance.
5. Assign the components:
   - **Basic**: Use **Select component** to choose one component.
   - **Modular**: Use **Select allowed components** to choose multiple components.
6. On the **Validations** tab, optionally mark the field as required.
7. On the **Advanced** tab, optionally enable [conditional visibility](https://hygraph.com/docs/developer-guides/schema/conditional-fields) to show the component field only when specific conditions are met. This is helpful for schemas with deeply nested structures.
8. Click **Add**.

## Use a component in a content entry

[Video](https://www.youtube.com/watch?v=cES1xbMCOS8)

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

- Basic component field — single value
- Basic component field — multiple values
- Modular component field — single value
- Modular component field — multiple values

**Note:**

**Studio UI limit:** The Studio UI supports linking up to **50 component instances** per entry (for both basic and modular fields). Instances beyond 50 remain fully queryable via the API, but won't appear in the UI. This limit exists because a large number of component instances can slow down queries and increase error risk.

To add a component instance to an entry:

1. In the **Content Editor**, open the relevant model and click **+ Add entry**.
2. Locate the component field in the entry form.
3. Add a component instance:
   - **Basic component field**: Click **+ Add component**.
   - **Modular component field**: Select a component from the dropdown.
4. Fill in the component instance fields.
5. If the field supports multiple instances, you can also:
   - **Duplicate** an instance: Click the context menu and select **Duplicate**. This copies the instance and its content.
   - **Copy**: Click the context menu and select **Copy**. This copies the instance and its content. You can then paste the component into the same entry or a different entry. See [Copy and paste component instances](#copy-and-paste-component-instances) for more details.
   - **Add another instance**: Click **+ Add new component**, or use **Add new item above** / **Add new item below** from the context menu.
   - **Reorder**: Use the context menu or arrow controls to reorder instances.
   - **Remove**: Click the context menu and select **Remove**. This deletes the instance.
   - **Remove all**: Click **Remove all**. This deletes all instances at once.

[Video: Duplicate component instances in an entry](https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmkgbmf6ozk2606uomkkajmni)

### Copy and paste component instances

You can copy a component instance from one entry and paste it into the same entry or a different entry, as long as the target entry allows the same component type. This also works with locales and nested components.

To copy and paste a component instance:

1. In the **Content Editor**, open the entry containing the component instance you want to copy.
2. Open the context menu on the component instance and select **Copy**.
3. Navigate to the target entry. This can be the same entry or a different one.
4. On the target component field, paste the copied component instance at the bottom of the list, or above or below a specific instance.
    - **At the bottom**: Click **+ Paste component**.
    - **Above a specific instance**: Click the context menu and select **Paste component above**.
    - **Below a specific instance**: Click the context menu and select **Paste component below**.

The pasted instance will appear with all its content pre-filled.

[Video: Copy and paste component instances](https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmmj24vr8ys0w07w2uhezxj98)

**Note:**

Paste is only available if you've copied a component instance that matches the target component field. If the component instance does not match, the **Paste** option will not appear.

## Nested components

Nested components let you add component fields inside other components, enabling hierarchical content structures.

**Example:** Create a **Section** component and a **Subsection** component, then nest the subsection inside the section.

[Video: Adding a nested component in the Schema Builder](https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9xuufjbqk07w5t5q77gny)

1. Open a component you've [already created](https://hygraph.com/docs/developer-guides/schema/components#create-a-component).
2. From the **Field types** sidebar, add a **Basic** or **Modular** component field to the parent component.
3. Enter the **Display name**. The **API ID** and **Plural API ID** are auto-populated but editable. Optionally, add a **Description**.
4. Assign the child components. Select a single component for a **Basic** component field, or multiple components for a **Modular** component field. 
    - **Important:** Only components you've already created appear in the dropdown. Make sure all required components exist before this step.
5. Click **Add**.

The nested component field now appears in the parent component's field list.

### Use nested components in an entry

After [setting up a nested component](https://hygraph.com/docs/developer-guides/schema/components#nested-components) in the Schema Builder, open a new entry and add the nested component as a subsection within the parent component.

**Note:**

The maximum supported nesting level is **4**.

![Adding nested components in a content entry](https://hygraph.com/images/docs/user-guides/components-addsubsection.png)

## Related docs

- [API reference for components](https://hygraph.com/docs/api-reference/schema/components) — How to query components via the API.
- [Components or references](https://hygraph.com/docs/developer-guides/schema/components-or-references) — Guidance on when to use components vs. references.